Relevant source files

The following files were used as context for generating this wiki page: - [SECURITY_SUMMARY.md](https://github.com/LoveLogicAILLC/secretforge-ai/blob/main/SECURITY_SUMMARY.md) - [PHASE1_IMPLEMENTATION.md](https://github.com/LoveLogicAILLC/secretforge-ai/blob/main/PHASE1_IMPLEMENTATION.md) - [SYSTEM_EVALUATION.md](https://github.com/LoveLogicAILLC/secretforge-ai/blob/main/SYSTEM_EVALUATION.md) - [packages/cli/src/storage/SecretStorage.ts](https://github.com/LoveLogicAILLC/secretforge-ai/blob/main/packages/cli/src/storage/SecretStorage.ts) - [packages/cli/src/\_\_tests\_\_/storage.test.ts](https://github.com/LoveLogicAILLC/secretforge-ai/blob/main/packages/cli/src/__tests__/storage.test.ts)

# Secret Storage Strategy The Secret Storage Strategy in SecretForge AI is a local-first architecture designed to secure sensitive credentials using industry-standard encryption and reliable local storage. The system prioritizes a zero-trust model where data remains on the developer's machine, encrypted at rest, and is only decrypted on-demand for specific operations. This strategy centers on a robust storage layer that integrates a SQLite database with an AES-256-GCM cryptographic provider. By combining persistent relational storage with authenticated encryption, SecretForge ensures confidentiality, integrity, and availability of secrets across different development environments and projects. Sources: [PHASE1_IMPLEMENTATION.md:12-15](), [PHASE1_IMPLEMENTATION.md:237-248](), [SECURITY_SUMMARY.md:65-72]() ## Architecture and Data Flow The storage architecture is divided into a modular directory structure that separates cryptographic logic from storage management. The primary interface for data persistence is the `SecretStorage` layer, which utilizes the `better-sqlite3` driver for synchronous, local operations. ### Data Flow for Secret Addition When a secret is added, the plaintext value is passed to a `CryptoProvider`, which generates a random IV and encrypts the value using AES-256-GCM. The resulting ciphertext, along with metadata such as tags and environment labels, is then persisted to the SQLite database. ```mermaid flowchart TD A[CLI / User Input] --> B{SecretStorage} B --> C[CryptoProvider] C --> D[Generate Random IV] D --> E[AES-256-GCM Encryption] E --> F[Create Secret Object] F --> G[(SQLite Database)] G --> H[Return Metadata to User] ``` The flow ensures that plaintext values are never stored directly on disk. Sources: [PHASE1_IMPLEMENTATION.md:18-35](), [PHASE1_IMPLEMENTATION.md:79-88](), [SECURITY_SUMMARY.md:46-55]() ## Database Schema SecretForge uses a relational schema to manage secrets with strict constraints to ensure data integrity and prevent duplication across environments. ### Secrets Table Definition | Field | Type | Constraints | Description | | :--- | :--- | :--- | :--- | | `id` | TEXT | PRIMARY KEY | Cryptographically secure unique identifier (UUID v4) | | `name` | TEXT | NOT NULL | The human-readable name of the secret (e.g., STRIPE_KEY) | | `project` | TEXT | NOT NULL | Identifier for the project the secret belongs to | | `environment` | TEXT | CHECK (dev, staging, prod) | Target environment for the secret | | `tags` | TEXT | DEFAULT '[]' | JSON array of strings for organizational filtering | | `value_encrypted`| TEXT | NOT NULL | The Base64-encoded ciphertext | | `created_at` | TEXT | NOT NULL | ISO timestamp of creation | | `updated_at` | TEXT | NOT NULL | ISO timestamp of last modification | **Note:** A unique constraint is enforced on the combination of `(name, project, environment)`. Sources: [PHASE1_IMPLEMENTATION.md:40-52](), [SECURITY_SUMMARY.md:104-108](), [packages/cli/src/__tests__/storage.test.ts:70-80]() ### Indexing Strategy To optimize performance for common CLI operations like listing and injecting secrets, the following indices are maintained: * `idx_project_env`: Optimized for filtering secrets by project and specific environments. * `idx_name`: Optimized for direct secret retrieval by key name. Sources: [PHASE1_IMPLEMENTATION.md:54-55]() ## Cryptographic Integration The storage strategy relies on the `DefaultCryptoProvider` to secure data before it reaches the database. This implementation adheres to NIST-approved standards. ### Encryption Properties * **Algorithm:** AES-256-GCM (Galois/Counter Mode). * **Key Management:** Derived from the `SECRETFORGE_ENCRYPTION_KEY` environment variable. * **Initialization Vector (IV):** A unique 12-byte random IV is generated for every encryption operation to prevent pattern detection. * **Integrity:** A 128-bit authentication tag is stored alongside the ciphertext to verify that data has not been tampered with. ```mermaid classDiagram class SecretStorage { <> +addSecret(options) +getSecret(id) +listSecrets(options) +updateSecret(id, value) +decryptSecret(secret) } class SQLiteSecretStorage { -db: Database -crypto: CryptoProvider +addSecret(options) +decryptSecret(secret) } class CryptoProvider { <> +encrypt(plaintext) +decrypt(ciphertext) } class DefaultCryptoProvider { -key: string +encrypt(plaintext) +decrypt(ciphertext) } SecretStorage <|.. SQLiteSecretStorage CryptoProvider <|.. DefaultCryptoProvider SQLiteSecretStorage --> CryptoProvider : uses ``` The relationship between storage and crypto providers allows for modular replacement of encryption logic (e.g., for future KMS integration). Sources: [SECURITY_SUMMARY.md:46-55](), [PHASE1_IMPLEMENTATION.md:61-75](), [SYSTEM_EVALUATION.md:65-75]() ## Storage Operations The `SQLiteSecretStorage` class implements the core CRUD logic required by the CLI. ### Secret Identification Secret IDs are generated using a cryptographically secure method to prevent prediction attacks. The format follows a `sec_` prefix followed by a hex-encoded UUID. ```typescript // Secure ID Generation Example private generateId(): string { const crypto = require('crypto'); return `sec_${crypto.randomUUID().replace(/-/g, '')}`; } ``` Sources: [SECURITY_SUMMARY.md:100-108](), [SYSTEM_EVALUATION.md:165-170]() ### Retrieval and Filtering The storage layer supports complex filtering during retrieval to accommodate the `sf list` and `sf export` commands. | Feature | Description | Implementation Detail | | :--- | :--- | :--- | | **Project Filtering** | Limits results to a specific project. | SQL `WHERE project = ?` | | **Env Filtering** | Filters by dev, staging, or prod. | SQL `WHERE environment = ?` | | **Tag Filtering** | Filters by specific metadata tags. | Parses JSON array in `tags` column. | | **Uniqueness** | Prevents duplicate names in the same env. | Enforced by SQLite UNIQUE constraint. | Sources: [PHASE1_IMPLEMENTATION.md:95-98](), [packages/cli/src/__tests__/storage.test.ts:140-165]() ## Security Safeguards The storage strategy includes several safeguards to protect sensitive data at rest and during execution: 1. **Memory Management:** Decrypted values are only held in memory for the duration of the request and are not cached. 2. **Key Isolation:** The encryption key is never stored in the database or the `.secretforge.json` configuration file. 3. **Sanitization:** Input values are escaped (backslashes and quotes) before storage to prevent injection attacks during later exports or injections. 4. **Audit Trail:** Every secret record includes `created_at` and `updated_at` timestamps to provide a basic audit history of secret lifecycle events. Sources: [SECURITY_SUMMARY.md:65-72](), [SECURITY_SUMMARY.md:80-90](), [SYSTEM_EVALUATION.md:180-185]() ## Conclusion SecretForge AI's Secret Storage Strategy provides a secure, reliable, and high-performance foundation for local secret management. By utilizing SQLite for structured persistence and AES-256-GCM for authenticated encryption, the system achieves a 5/5 security rating for data protection. The architecture is designed to scale from local development to CI/CD workflows while maintaining a zero-trust posture.