🛡️ MinSec

Lightweight, Zero-Knowledge E2EE Secrets & Configuration Manager
Zero-Disk In-Memory Injection • AI Coding Assistant Protection • Cloudflare D1 & SQLite Dual-Mode

English | 简体中文 | 日本語

📖 Table of Contents

• Why MinSec? (Core Problem Solved)
  • 1. The AI IDE / LLM Security Blindspot
  • 2. Pain-Free Team Collaboration & Instant Revocation
  • 3. Intranet & Serverless Data Sovereignty
• Global Installation (npm / pnpm / yarn)
• Architecture & Encryption Flow
• Deployment Modes
  • Option A: Local / Corporate Intranet (SQLite)
  • Option B: Serverless (Cloudflare Workers + D1)
• CLI Commands Reference
• Web Management Dashboard
• ⚠️ Critical Backup Warning: Root Key
• Configuration Specification (.minsec)
• License & Commercial Inquiries

💡 Why MinSec? (Core Problem Solved)

1. The AI IDE / LLM Security Blindspot

Modern AI coding assistants (such as Claude Code, Cursor, GitHub Copilot, Codex, Gemini Code Assist, etc.) frequently scan, index, and upload the contents of your workspace to remote LLM servers to build context.

• The Danger: Traditional projects store unencrypted credentials in plaintext .env files on disk (DATABASE_URL, STRIPE_SECRET_KEY, AWS_SECRET_ACCESS_KEY, etc.). Developers often accidentally leak these sensitive keys directly into LLM training prompts or third-party cloud logs.
• The MinSec Solution: Zero-Disk In-Memory Secret Injection.

  minsec run -- npm run dev

  Secrets are fetched via encrypted network stream and injected directly into process RAM (process.env) at startup. Zero secret files are written to disk. The workspace only contains a safe, shareable .minsec manifest.

2. Pain-Free Team Collaboration & Instant Revocation

• No More Plaintext Sharing: Stop passing .env files through Slack, WeChat, email, or zip archives.
• Instant Offboarding: When a developer or contractor leaves the team, administrators can revoke their scoped API Key in the Web UI with a single click. Their local CLI immediately loses access to all secrets.
• Single-Point Secret Rotation: When a database password or API token changes, update it once on the MinSec dashboard. Every team member and CI/CD pipeline immediately receives the new secret upon the next command run—no manual .env synchronization needed.

3. Intranet & Serverless Data Sovereignty

MinSec can be self-hosted completely offline within a private corporate intranet, or deployed globally in seconds across Cloudflare's serverless edge network. You maintain 100% control over where your secrets are stored and who can decrypt them.

📦 Global Installation (npm / pnpm / yarn)

Install minsec globally using your preferred package manager to make the minsec command available everywhere across your system:

# Using npm
npm install -g minsec

# Using pnpm
pnpm add -g minsec

# Using yarn
yarn global add minsec

Once installed globally, you can invoke minsec and minsec-server from any directory:

# Verify installation
minsec --help

# Start the local daemon & dashboard
minsec server

🔒 Architecture & Encryption Flow

MinSec implements strict Zero-Knowledge Envelope Encryption:

                               ┌──────────────────────────────────────────────┐
                               │       Master Root Key (256-bit AES-GCM)       │
                               │  (Saved in ~/.minsec/server.key or CF Secret)│
                               └──────────────────────┬───────────────────────┘
                                                      │ Encrypts / Decrypts
                                                      ▼
┌──────────────────────┐       ┌──────────────────────────────────────────────┐
│  Config Value Plain  │ ───►  │        Project Key (256-bit AES-GCM)         │
└──────────────────────┘       └──────────────────────┬───────────────────────┘
                                                      │ Encrypts
                                                      ▼
                               ┌──────────────────────────────────────────────┐
                               │ Ciphertext stored in D1 / SQLite Database    │
                               └──────────────────────────────────────────────┘

1. Root Key: Highest authority key, stored exclusively on your host environment (~/.minsec/server.key or Cloudflare Worker Secret).
2. Project Key: Each project generates a dedicated 256-bit AES-GCM key, encrypted by the Root Key.
3. Ciphertext Storage: All secrets in the database are stored as salted AES-GCM ciphertext. Plaintext never touches disk storage.

🚀 Deployment Modes

Option A: Local / Corporate Intranet (SQLite)

MinSec includes a built-in lightweight server powered by Hono and local SQLite.

# Option 1: If globally installed
minsec server --port 9876

# Option 2: Running from cloned source
npm install
node bin/minsec-server

Open your browser and visit http://localhost:9876/ to set up the initial Administrator account.

Option B: Serverless (Cloudflare Workers + D1)

Deploy a globally distributed, high-availability MinSec instance with a single command:

minsec deploy cloudflare

The deployment automation handles everything for you:

1. Verifies your Cloudflare wrangler authentication;
2. Automatically provisions a Cloudflare D1 database (minsec-db);
3. Executes unified SQLite schema migrations on remote D1;
4. Generates and securely uploads MINSEC_ROOT_KEY and JWT_SECRET to Worker Secrets;
5. Deploys the unified Cloudflare Worker (serving both the REST API and the embedded SPA Web Dashboard) and returns your public endpoint:

   🌐 MinSec Endpoint: https://minsec-api.<your-subdomain>.workers.dev

💻 CLI Commands Reference

Global Credential Configuration

# Point CLI to your Cloudflare or on-premise server
minsec config set --global --endpoint https://minsec-api.your-domain.workers.dev --key ms_tok_...

# Inspect active configuration and linkage
minsec config

Initialize Workspace Linkage

Run in your project root directory (creates .minsec):

minsec init

• Prompts for Server Endpoint, API Key, Project, Environment (dev/staging/prod), and Path (/).
• Automatically detects Monorepo architectures (apps/*, packages/*) and offers sub-project linkage.

Run Process with In-Memory Secrets (Zero-Disk)

minsec run injects variables directly into the child process's OS environment block (env). Because this operates at the OS kernel level, it works seamlessly with any programming language and runtime (Node.js, Go, Rust, Java, Python, Docker, etc.) without additional configuration.

# Node.js
minsec run -- npm run dev
minsec run --env prod --path /apps/web -- npm start

# Go (Development or Compiled Binary)
minsec run -- go run main.go
minsec run -- ./bin/server

# Rust (Cargo or Release Binary)
minsec run -- cargo run
minsec run -- ./target/release/my-app

# Java (Spring Boot, Gradle, or Executable JAR)
minsec run -- ./mvnw spring-boot:run
minsec run -- ./gradlew bootRun
minsec run -- java -jar target/app.jar

# Python / Shell / Any CLI
minsec run -- python main.py
minsec run -- docker compose up

Multi-Language In-Code Access

| Language | Code Access | Note | | :--- | :--- | :--- | | Node.js | process.env.DATABASE_URL | Standard library | | Go | os.Getenv("DATABASE_URL") | Standard library | | Rust | std::env::var("DATABASE_URL") | Standard library | | Java | System.getenv("DATABASE_URL") | ⚠️ Note: MinSec injects OS-level environment variables. In Java, you must use System.getenv(...) instead of System.getProperty(...) (which is only for JVM -D flags). Modern frameworks like Spring Boot automatically map OS environment variables into application.yml or @Value("${database.url}"). | | Python | os.getenv("DATABASE_URL") | Standard library |

Read & Write Secrets via CLI

# Set a configuration variable
minsec set PORT=3000

# Set an encrypted secret
minsec set STRIPE_KEY=sk_live_1234567890 --secret

# List configurations for current project/env/path
minsec list

Export & Import Encrypted Bundles

# Export selected projects into a password-protected bundle (.minsec.vault)
minsec export --projects my-project,auth-service --output backup.minsec.vault

# Import bundle with automatic collision resolution
minsec import backup.minsec.vault

Emergency Password Reset (Local Server)

minsec reset-password --username admin

🖥️ Web Management Dashboard

MinSec embeds a complete, responsive Single-Page Application (SPA) directly into both the local server and the Cloudflare Worker root URL (/):

• Multi-Project Organization: Manage isolated projects with instant switching.
• Monorepo Hierarchical Paths: Organize microservices or monorepo packages by paths (e.g. /, /apps/web, /apps/billing). Child paths seamlessly inherit variables from root /.
• Multi-Environment Support: Built-in dev, staging, prod support with custom environment creation.
• Cross-Environment Sync (🔄 同步变量): Copy variable definitions from one environment to another in 1-click (keys only or with values).
• Project-Scoped API Tokens: Issue granular API tokens restricted to specific projects and set expiration dates (7d, 30d, 90d, 1y, or never).
• Selective Project Export & Import: Selectively package multiple projects into AES-256-GCM encrypted .minsec.vault files.
• Safe Project Deletion: Enforces a strict empty-item guard; projects can only be deleted when item count is 0.
• One-Click Project ID & Template Copy:
  • ID: <projectId> 📋: Click to copy the exact project ID.
  • 📋 Copy .minsec: Generates and copies ready-to-paste JSON configuration for your workspace.

⚠️ Critical Backup Warning: Root Key

[!CAUTION] PLEASE BACK UP YOUR ROOT KEY IMMEDIATELY UPON DEPLOYMENT! MinSec operates under zero-knowledge envelope encryption. If your Root Key is lost, all encrypted secrets in the database are permanently and irreversibly unrecoverable.

1. For Local Deployments:
   • Back up the file: ~/.minsec/server.key
   • Store it in a secure, encrypted offline location (e.g. KeePass, 1Password, or cold storage).
2. For Cloudflare Deployments:
   • Back up the MINSEC_ROOT_KEY value generated during deployment.
   • You can inspect or manage this secret in Cloudflare Dashboard:
     Workers & Pages ➔ minsec-api ➔ Settings ➔ Variables and Secrets ➔ MINSEC_ROOT_KEY.

📋 Configuration Specification (.minsec)

A typical workspace .minsec linkage file:

{
  "endpoint": "",
  "apiKey": "",
  "projectId": "my-service",
  "projectName": "my-service",
  "defaultEnv": "dev",
  "defaultPath": "/"
}

• Inheritance: If endpoint or apiKey is empty (""), the CLI automatically inherits credentials from your user-global configuration (~/.minsec/.minsec).
• Flexibility: projectId accepts either the system-generated ID (prj_...) or your chosen project name (my-service). Both are natively supported by the backend.

📄 License & Commercial Inquiries

This project is released under the Non-Commercial Open Source License (MinSec Version 1.0).

• Free for Non-Commercial Use: Free to use, modify, and self-host for personal projects, internal study, educational research, and non-profit organizations.
• Commercial License Required: Any commercial use, deployment within a commercial company or enterprise, or use as a commercial/SaaS product strictly requires an official commercial authorization / license from the author.

For commercial licensing, enterprise support, or authorization inquiries, please contact the author.