Runtime Secret Injection
Relevant source files
The following files were used as context for generating this wiki page:
Runtime Secret Injection is a core security feature of SecretForge AI designed to securely bridge the gap between encrypted secret storage and application execution environments. It enables developers to retrieve encrypted secrets from a local SQLite database and "inject" them into environment-specific files (e.g., .env.dev, .env.prod) or export them for CI/CD pipelines without exposing sensitive values in plain text within the version control system.
The system utilizes an AES-256-GCM encryption layer to ensure that secrets remain "at rest" in an encrypted state, only being decrypted during the injection process when required by the target runtime environment. This mechanism supports a local-first, zero-trust model where sensitive credentials like Stripe keys or AWS tokens never touch the cloud or persistent configuration files in their raw form.
Sources: SECURITY_SUMMARY.md, PHASE1_IMPLEMENTATION.md:7-14, SYSTEM_EVALUATION.md:143-150
Injection Architecture and Logic
The injection process is handled primarily through the CLI's inject and export commands. The architecture follows a flow where the user specifies a target environment (dev, staging, or prod), and the system performs a lookup in the local SQLite database.
Core Logic Flow
When the sf inject command is invoked, the system follows these logical steps:
- Environment Selection: The user identifies which environment's secrets to fetch.
- Database Query: The system queries the
secretstable for entries matching the specified project and environment. - Decryption: Using the
DefaultCryptoProviderand theSECRETFORGE_ENCRYPTION_KEY, the system decrypts thevalue_encryptedfield. - Sanitization: Values are sanitized to prevent shell injection or environment variable corruption.
- Output Generation: The decrypted values are merged with existing variables and written to the target
.envfile or standard output.
This diagram illustrates the secure data flow from the encrypted database to the final environment file.
Sources: PHASE1_IMPLEMENTATION.md:105-125, SECURITY_SUMMARY.md:65-72
Secure Decryption Layer
The injection process relies on the CryptoProvider interface to perform industry-standard decryption. The system uses AES-256-GCM with a random 12-byte Initialization Vector (IV) and a 128-bit authentication tag.
Encryption Properties
| Property | Specification | Implementation Detail |
|---|---|---|
| Algorithm | AES-256-GCM | NIST-approved Galois/Counter Mode |
| Key Source | SECRETFORGE_ENCRYPTION_KEY | 256-bit Base64-encoded environment variable |
| Integrity | Authentication Tag | Prevents tampering during injection |
| Freshness | Random IV | Unique ciphertext per encryption event |
Sources: SECURITY_SUMMARY.md:32-48, PHASE1_IMPLEMENTATION.md:61-75
Input Sanitization and Escaping
To prevent shell injection and corruption of environment variable files, the injection command applies strict sanitization logic. This ensures that special characters like backslashes (\) and double quotes (") are handled correctly when generating .env or YAML outputs.
// Example of escaping logic used during secret injection
// Prevents shell injection and formatting errors
const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
Sources: SECURITY_SUMMARY.md:83-93, SYSTEM_EVALUATION.md:76-85
CLI Command Specifications
The injection functionality is exposed through the sf binary, specifically via the inject and export sub-commands.
Command Parameters
| Command | Options | Description |
|---|---|---|
sf inject | --env <environment> | Targets 'dev', 'staging', or 'prod'. |
--file <path> | Custom destination (Default: .env.<environment>). | |
sf export | --env <environment> | Fetches secrets for the selected environment. |
--format <type> | Formats: env, json, or yaml. |
Integration Sequence
The following sequence diagram shows the interaction between the user, the CLI, and the storage layer during a standard injection task.
The sequence demonstrates that decryption only occurs in-memory during the execution of the command and is never persisted in an unencrypted state within the database.
Sources: PHASE1_IMPLEMENTATION.md:105-125, packages/cli/src/sf.ts
Security Mitigations and Compliance
Runtime Secret Injection addresses several threats identified in the project's threat model:
- Tampering: GCM authentication tags verify data integrity before injection.
- Injection Attacks: Proper escaping in
inject.tsprevents shell-based attacks via crafted secret values. - Leakage: Values are masked in standard list views and only decrypted during explicit export/injection actions.
The implementation supports GDPR (Right to delete via sf delete) and HIPAA (Unique identifiers and encryption at rest) by ensuring that the injection process is an ephemeral transition from an encrypted state to a local runtime environment.
Sources: SECURITY_SUMMARY.md:112-127, SECURITY_SUMMARY.md:144-160
Conclusion
Runtime Secret Injection provides a secure, local-first method for managing application configuration. By combining AES-256-GCM encryption with strict output sanitization, SecretForge ensures that developers can maintain a zero-trust environment where sensitive credentials are only decrypted at the moment they are needed for local execution or CI/CD deployment. This architecture effectively eliminates the risk of committing plain-text secrets to version control.