Local Persistence & Secure Storage
Relevant source files
The following files were used as context for generating this wiki page:
Local Persistence and Secure Storage in Termul manage the lifecycle of application state, session data, and sensitive configuration. The system uses a multi-layered approach to save data across application restarts, combining a high-level persistence API with platform-specific adapters. In the desktop environment, the system utilizes the Tauri plugin-store to write data to the local filesystem, while specialized persistence logic handles session recovery and MCP (Model Context Protocol) registry synchronization.
The architecture ensures data integrity through versioning and optimizes performance by debouncing frequent write operations. Secure storage specifically handles sensitive information like SSH passwords and key passphrases by leveraging the OS keychain rather than plaintext files.
Persistence Architecture
The persistence system operates through a unified facade that branches behavior based on the execution context. In the Tauri desktop runtime, the tauriPersistenceApi acts as the primary interface for data operations.
Core Data Operations
The system provides standard CRUD operations wrapped in an IpcResult pattern to ensure consistent error handling across the application.
- Read: Retrieves versioned or legacy data from the store.
- Write: Commits data to the store immediately.
- Write Debounced: Postpones the write operation by 500ms to coalesce multiple updates into a single disk write.
- Delete/Remove: Removes a key and its associated data from the store.
- Flush: Forcefully executes all pending debounced writes.
Sources: src/renderer/lib/tauri-persistence-api.ts:88-150, src/renderer/lib/tests/tauri-persistence-api.test.ts:74-130
Logic Flow for Debounced Writes
The following diagram illustrates how the tauriPersistenceApi handles debounced write requests to prevent excessive disk I/O.
The system maintains a Map of pending entries to ensure that only the latest value for a specific key is persisted when the timer expires.
Sources: src/renderer/lib/tauri-persistence-api.ts:46-86, src/renderer/lib/tests/tauri-persistence-api.test.ts:133-159
Session Persistence
The tauriSessionApi specializes in managing the state of terminals and workspaces. It ensures that user contexts, including command history and active tabs, survive application restarts.
Session Data Structure
Sessions are stored under the sessions/auto-save key and follow a specific schema.
| Field | Type | Description |
|---|---|---|
timestamp | string | ISO string of the last save time. |
terminals | TerminalData[] | Array of terminal states (ID, shell, CWD, history, env). |
workspaces | WorkspaceData[] | Array of project-specific layouts and active terminals. |
_version | number | Schema version for migration purposes (Current: 1). |
Sources: src/renderer/lib/tauri-session-api.ts:1-20, src/renderer/lib/tests/tauri-session-api.test.ts:44-65
Session Lifecycle Management
The session API validates data before persistence to prevent corruption. If save is called with missing terminal IDs or empty workspace project IDs, the API returns a SESSION_INVALID error. During restoration, the system verifies the existence of the sessions/auto-save key; if missing, it returns SESSION_NOT_FOUND.
Sources: src/renderer/lib/tests/tauri-session-api.test.ts:107-140
MCP Registry Persistence and Sync
The Model Context Protocol (MCP) registry persistence handles the storage of agent servers. This module implements a dual-write strategy to keep application settings in sync with project-level configurations.
Synchronization Logic (CAP-7)
When running in the Tauri desktop environment, saving MCP servers triggers two distinct actions:
- App-Store Write: The primary source of truth is updated via the
persistenceApiusing theacp-mcp-serverskey. - Project-File Sync: The system attempts to mirror the registry to a project-specific file via
syncMcpRegistryToProject.
If the project-file sync fails, the system logs a MCP_REGISTRY_WRITE_ERROR but does not halt the primary save operation, as the sync is considered non-fatal.
Sources: src/renderer/lib/acp-mcp-persistence.ts, src/renderer/lib/tests/acp-mcp-persistence.test.ts:98-140
Secure Storage for Sensitive Data
Termul delegates the management of credentials to the operating system's native keychain to avoid storing secrets in plaintext on the disk.
SSH Credential Handling
- Keychains: SSH passwords and private key passphrases are stored via the OS keychain.
- Prohibited Storage: The system explicitly forbids storing secrets in
ssh-profiles.json. - Memory Retention: Active SSH sessions may retain secrets in process memory only to support automatic reconnection.
- Recommendation: Users are encouraged to use SSH agent authentication to minimize runtime secret retention in memory.
Sources: README.md: SSH Development Notes
Data Integrity and Parity
Termul enforces strict parity between desktop and web environments. The renderer uses an adapter layer to ensure that platform-specific implementations (Tauri vs. Web) adhere to the same API contracts.
Parity Checklist (P0 Domains)
The project includes automated checks to verify that critical persistence domains are correctly implemented in Tauri.
| Domain | Implementation File | Key Methods |
|---|---|---|
| Session | tauri-session-api.ts | save, restore, clear, flush, hasSession |
| Data Migration | tauri-data-migration-api.ts | runMigration, getHistory, rollback, getVersion |
| Persistence | tauri-persistence-api.ts | read, write, writeDebounced, delete, flush |
Sources: src/renderer/lib/tests/parity-checklist.test.ts:143-165, src/renderer/lib/tests/tauri-persistence-api.test.ts:250-270
Security Constraints in Source Code
The biome.json configuration enforces architectural boundaries by preventing UI components from importing Tauri APIs directly. All persistence operations must go through the library facades located in src/renderer/lib/.
Sources: biome.json:48-58
Summary
Local Persistence & Secure Storage provides the foundation for Termul's "project-aware" memory. By utilizing Tauri's store for general data, specific session logic for workspace recovery, and the OS keychain for sensitive credentials, the system balances user convenience with high security standards. The debounced write mechanism and strict API facades further ensure that the application remains performant and maintainable across both desktop and web platforms.