CLI Cryptography Provider

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/crypto/CryptoProvider.ts
• packages/cli/src/tests/crypto.test.ts
• SYSTEM_EVALUATION.md
• PHASE1_IMPLEMENTATION.md
• SECURITY_SUMMARY.md
• packages/cli/CLI_README.md

The CLI Cryptography Provider is a core security component of SecretForge AI responsible for ensuring the confidentiality and integrity of secrets stored locally. It serves as the primary interface for all encryption and decryption operations within the CLI package, implementing industry-standard algorithms to protect sensitive data at rest.

The provider is designed with a "local-first" philosophy, relying on an environment-based master key to perform cryptographic operations without the need for external cloud dependencies. It abstracts the complexities of the Node.js crypto module into a simple, promise-based interface used by the Secret Storage layer.

Sources: PHASE1_IMPLEMENTATION.md, SYSTEM_EVALUATION.md

Cryptographic Architecture

The system utilizes the CryptoProvider interface to define standard cryptographic behaviors, with DefaultCryptoProvider as the concrete implementation used in Phase 1.

Core Interface

The interface provides two primary methods that handle the lifecycle of secret protection:

• encrypt(plaintext: string): Promise<string>: Transforms raw data into a secure, encoded string.
• decrypt(encryptedValue: string): Promise<string>: Reverts encoded data back to its original plaintext.

Sources: packages/cli/src/crypto/CryptoProvider.ts:1-6, SYSTEM_EVALUATION.md

Cryptographic Specification

The implementation follows NIST-approved standards to ensure robust security:

Component	Specification	Description
Algorithm	AES-256-GCM	Advanced Encryption Standard in Galois/Counter Mode.
Key Size	256 bits	32-byte master key.
IV	12 bytes	Random Initialization Vector generated per encryption.
Auth Tag	128 bits	Authentication tag used to verify data integrity and prevent tampering.
Encoding	Base64	Final output format for storage in SQLite.

Sources: SECURITY_SUMMARY.md, PHASE1_IMPLEMENTATION.md

Encryption Logic and Data Flow

The encryption process ensures that even identical plaintexts result in different ciphertexts by utilizing a unique Initialization Vector (IV) for every operation.

Security Properties

1. Confidentiality: Provided by the AES-256 block cipher.
2. Integrity: Guaranteed by the GCM Authentication Tag; any modification to the stored string causes decryption to fail.
3. Freshness: Provided by the random 12-byte IV, preventing pattern analysis (semantic security).

Sources: SECURITY_SUMMARY.md, packages/cli/src/crypto/CryptoProvider.ts

Key Management

The CLI Cryptography Provider implements an "external key" strategy. The master encryption key is never stored within the application's configuration or database files.

Key Requirements

• Variable Name: SECRETFORGE_ENCRYPTION_KEY
• Format: Base64-encoded string.
• Source Size: Must represent 32 bytes of raw data.
• Validation: The provider validates key length during initialization and throws an error if the key is missing or invalid.

Sources: packages/cli/CLI_README.md, SECURITY_SUMMARY.md

Key Generation

A secure key can be generated using standard cryptographic utilities:

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Using OpenSSL
openssl rand -base64 32

Sources: packages/cli/CLI_README.md, PHASE1_IMPLEMENTATION.md

Implementation Details

The implementation leverages the Node.js crypto module. During decryption, the provider must extract the IV and Auth Tag from the stored string to successfully reconstruct the plaintext.

Error Handling

The provider is tested to handle various failure states:

• Missing Key: Throws an error if SECRETFORGE_ENCRYPTION_KEY is undefined.
• Invalid Key: Validates that the provided key can be used for AES-256.
• Tampering: Decryption fails if the ciphertext or authentication tag has been modified.
• Malformed Input: Handles empty strings or non-base64 inputs gracefully via rejection.

Sources: packages/cli/src/tests/crypto.test.ts:1-50, SECURITY_SUMMARY.md

Performance Metrics

The Cryptography Provider is optimized for high-performance CLI interactions, ensuring minimal latency during secret injection or retrieval.

Operation	Average Latency	Context
Encryption	~5ms	Includes IV generation and Base64 encoding.
Decryption	~3ms	Includes tag verification and decoding.
Batch Injection	~500ms	Performance for 100+ secrets (includes disk I/O).

Sources: PHASE1_IMPLEMENTATION.md, SYSTEM_EVALUATION.md

Summary

The CLI Cryptography Provider establishes the security foundation for SecretForge AI. By implementing AES-256-GCM with mandatory authentication tags and unique initialization vectors, it ensures that secrets stored in the local SQLite database remain secure even if the database file is compromised. Its reliance on environment-based key management aligns with zero-trust security principles, keeping the "keys to the kingdom" entirely under the user's control.

Sources: SECURITY_SUMMARY.md, PHASE1_IMPLEMENTATION.md