High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
SecretForge AI is an AI-powered secret management platform designed to automate the detection, provisioning, and rotation of API keys. The system follows a local-first philosophy for developer tools while leveraging a globally distributed edge-native backend for AI processing and collaborative features. It is built on a zero-knowledge architecture where secrets are encrypted before storage and decrypted only on-demand by authorized components.
The architecture is structured as a Turborepo-based monorepo, integrating a Cloudflare Workers API, a Next.js web dashboard, a specialized Command-Line Interface (CLI), and a Model Context Protocol (MCP) server for AI assistant integration.
Sources: README.md:14-22, WARP.md:57-64, PHASE1_IMPLEMENTATION.md:5-9
System Component Overview
The SecretForge ecosystem consists of several interconnected packages that facilitate secure secret lifecycles from local development to production CI/CD pipelines.
Core Packages
| Package | Technology | Purpose |
|---|---|---|
packages/api | Hono, Cloudflare Workers | Edge-native API handling AI agents, D1, KV, and Vectorize storage. |
packages/cli | Commander, Ollama | Local-first tool for secret encryption, storage, and injection. |
packages/web | Next.js, Tailwind CSS | Dashboard for visual secret management and compliance tracking. |
packages/mcp-server | @modelcontextprotocol/sdk | Integration layer for AI assistants like Claude Code. |
packages/shared | TypeScript | Shared utilities, types, and AST-based code analyzers. |
Sources: README.md:143-153, WARP.md:59-64
System Interaction Flow
The following diagram illustrates how various clients interact with the Cloudflare-based infrastructure.
The system leverages Cloudflare Agents for stateful AI operations, utilizing embedded SQLite for state management and GPT-4o for processing.
Sources: README.md:56-83, LAUNCH_PLAN.md:106-111
Local Storage and Security Architecture
The packages/cli implements a secure, local-first storage layer using SQLite. This ensures that developer secrets remain on their machines unless explicitly shared.
Security Implementation
SecretForge employs AES-256-GCM for all encryption operations. This NIST-approved algorithm provides both confidentiality and integrity via an authentication tag.
- Key Management: The encryption key is derived from the
SECRETFORGE_ENCRYPTION_KEYenvironment variable and is never stored in the database or config files. - Initialization Vector (IV): A random 12-byte IV is generated for every encryption operation to prevent pattern detection.
- ID Generation: Cryptographically secure UUIDs (
crypto.randomUUID()) are used for secret identifiers.
Sources: SECURITY_SUMMARY.md:36-64, PHASE1_IMPLEMENTATION.md:58-71
Data Model (D1/SQLite)
The relational schema used in both the local CLI and the Cloudflare D1 backend manages secret metadata while keeping the actual values encrypted.
| Field | Type | Description |
|---|---|---|
id | TEXT | Primary Key (Secure UUID). |
name | TEXT | Human-readable name (e.g., STRIPE_API_KEY). |
project | TEXT | Project identifier. |
environment | TEXT | dev, staging, or prod (Enum constraint). |
tags | TEXT | JSON array for organization. |
value_encrypted | TEXT | AES-256-GCM encrypted payload. |
created_at | TEXT | ISO timestamp. |
Sources: PHASE1_IMPLEMENTATION.md:33-46, SYSTEM_EVALUATION.md:270-275
AI-Powered Logic and Analyzers
A key architectural differentiator is the inclusion of static code analyzers and AI agents to determine required permissions automatically.
Scope Optimization
The ScopeOptimizer in packages/shared uses AST-like regex parsing to analyze project source code in multiple languages (JavaScript, Python, Go) to detect API calls.
The analyzer maps detected methods (e.g., stripe.customers.create) to specific scopes (e.g., customers:write) to ensure the principle of least privilege.
Sources: packages/shared/src/analyzers/scopeOptimizer.ts:8-100, README.md:25-33
Cloudflare Agents
The backend utilizes the Cloudflare Agents API to provide a "stateful AI" experience. These agents manage complex workflows like key rotation and compliance validation (SOC2, GDPR, HIPAA) by maintaining internal state in embedded SQLite databases within the edge worker context.
Sources: README.md:79-82, LAUNCH_PLAN.md:106-111
Deployment and CI/CD Integration
SecretForge is designed to be integrated directly into the software development lifecycle (SDLC) via GitHub Actions.
GitHub Action Workflow (SecretForge Shield)
The packages/github-action (SecretForge Shield) serves as a viral growth engine and security gate. It scans Pull Requests for exposed secrets and can automatically provision secure replacements.
Sources: BUILT.md:7-19, LAUNCH_PLAN.md:76-88
Infrastructure Configuration
The system uses wrangler for managing Cloudflare resources:
- D1: Relational storage for metadata.
- KV:
SECRETS_VAULTfor edge-side secret caching. - Vectorize:
api-docs-indexfor semantic search of API documentation.
Sources: README.md:179-195, WARP.md:76-78
Conclusion
SecretForge AI's architecture effectively bridges the gap between high-security secret storage and AI-driven automation. By combining a local-first CLI for encryption with edge-native AI agents for intelligence, it provides a scalable framework that enforces the principle of least privilege while automating the traditionally manual tasks of key provisioning and rotation. Its integration with the Model Context Protocol (MCP) further positions it as a native security layer for the next generation of AI-assisted development tools.
Sources: SYSTEM_EVALUATION.md:435-445, BUILT.md:145-165