Environment Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Environment Configuration system in SecretForge AI is designed to manage sensitive credentials and project settings across various deployment stages, including development, staging, and production. It utilizes a combination of environment variables, local configuration files, and encrypted SQLite databases to ensure that API keys and other secrets are managed securely without ever being committed to version control.
The system supports a local-first architecture where secrets are encrypted at rest using AES-256-GCM. This configuration framework allows developers to initialize secure workspaces, inject environment-specific secrets into .env files, and manage global settings for AI services like OpenAI, Anthropic, and Cloudflare.
Sources: README.md:14-23, PHASE1_IMPLEMENTATION.md:10-18
Core Configuration Components
Project-Level Configuration
SecretForge uses a central configuration file, .secretforge.json, to manage project-specific metadata. This file acts as the bridge between the CLI tool and the underlying encrypted storage.
| Configuration Element | Type | Description |
|---|---|---|
version | string | The version of the configuration schema (e.g., "1.0.0"). |
project | string | The unique identifier or name of the project. |
defaultEnvironment | string | The default stage (dev, staging, or prod) for secret operations. |
databasePath | string | The local filesystem path to the project's encrypted SQLite database. |
Sources: PHASE1_IMPLEMENTATION.md:73-82
Environment Variables
Environment variables serve as the primary mechanism for providing high-level API keys to the system and for managing the master encryption key required for local storage.
# Example .env setup
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
ENCRYPTION_KEY=32_byte_base64_encoded_key
SECRETFORGE_API=https://api.secretforge.ai
Sources: WARP.md:57-61, README.md:162-170
Setup and Initialization Flow
The initialization process prepares the local environment by generating necessary keys and establishing the directory structure.
The diagram above illustrates the sequence of operations required to transition a fresh environment into a functional SecretForge workspace.
Sources: WARP.md:16-31, PHASE1_IMPLEMENTATION.md:85-92, scripts/launch.sh:100-110
Deployment Stages and Scopes
SecretForge enforces strict environment separation. Secrets are scoped to specific environments to prevent accidental leakage of production credentials into development workflows.
Supported Environments
The system validates environments against a fixed set of allowed values:
- dev: Local development and testing.
- staging: Pre-production validation.
- prod: Production deployment.
Sources: PHASE1_IMPLEMENTATION.md:46-50, packages/mcp-server/src/index.ts:36-40
Secret Injection Architecture
The sf inject command facilitates the movement of secrets from the encrypted storage into the local runtime environment files used by frameworks like Next.js or Cloudflare Workers.
The sequence shows how the CLI safely handles decrypted data only during the injection phase, ensuring values are properly escaped for shell compatibility.
Sources: PHASE1_IMPLEMENTATION.md:104-113, SECURITY_SUMMARY.md:65-75
Security Configuration
Encryption Standards
The environment configuration relies on AES-256-GCM for all secrets at rest.
| Security Property | Implementation Details |
|---|---|
| Algorithm | AES-256-GCM (NIST Approved) |
| Key Management | SECRETFORGE_ENCRYPTION_KEY via Environment Variable |
| IV Generation | Random 12-byte per encryption |
| Integrity | 128-bit Authentication Tag |
Sources: SECURITY_SUMMARY.md:27-41, PHASE1_IMPLEMENTATION.md:54-65
Git Best Practices
To maintain environment security, the configuration system defines a clear boundary for version control:
- Committed:
package.json,.secretforge.json,wrangler.toml. - Ignored:
.env,.env.*,~/.secretforge/*.db.
Sources: PHASE1_IMPLEMENTATION.md:143-145, AUTOMATION_SUMMARY.md:33-40
API and Cloud Configuration
When deploying the API package to Cloudflare Workers, environment configuration is managed via the wrangler.toml and specific Cloudflare bindings.
Resource Bindings
The API integration requires several Cloudflare-specific environment configurations:
- D1 Database:
secretforge-dbfor relational storage. - KV Namespace:
SECRETS_VAULTfor fast secret retrieval. - Vectorize Index:
api-docs-indexfor AI-powered documentation search.
Sources: README.md:150-160, packages/api/src/tests/api.integration.test.ts:10-20
Test Environment Mocking
For integration testing, the environment is simulated using mock namespaces to avoid side effects on production resources. This includes mocking JWT secrets and rate limit KV stores.
Sources: packages/api/src/tests/api.integration.test.ts:25-30
Summary
Environment Configuration in SecretForge AI is a multi-layered system that prioritizes local security and environment isolation. By combining project-specific JSON configuration with AES-encrypted SQLite databases and environment variables, the system provides a robust framework for managing secrets across the development lifecycle. This structure allows the CLI, MCP server, and API to maintain a zero-trust posture while offering seamless integration with developer workflows.