@fentz26/envcp 1.0.0 → 1.0.2

package/.github/workflows/publish.yml

@@ -2,14 +2,14 @@ name: Publish to npm
 
 on:
   push:
-    branches: [main]
     tags: ['v*']
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
+      packages: write
     steps:
       - uses: actions/checkout@v4
 
@@ -25,3 +25,24 @@ jobs:
       - run: npm publish --access=public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Publish to GitHub Packages
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - run: npm publish --access=public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Create GitHub Release
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          gh release create "$TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$TAG" \
+            --generate-notes

package/README.md

@@ -2,50 +2,7 @@
 
 **Secure Environment Variable Management for AI-Assisted Coding**
 
-EnvCP is a universal tool server that allows developers to safely use AI assistants for coding without exposing sensitive environment variables, API keys, or secrets. Works with Claude, ChatGPT, Gemini, Cursor, and any AI tool.
-
-## Why EnvCP?
-
-When using AI coding assistants, you often need to reference environment variables, API keys, or other secrets. But you don't want to share these with the AI. EnvCP solves this by:
-
-- **Local-only storage** - Your secrets never leave your machine
-- **Encrypted at rest** - AES-256-GCM encryption with PBKDF2 key derivation (100,000 iterations)
-- **Reference-based access** - AI references variables by name, never sees the actual values
-- **Automatic .env injection** - Values can be automatically injected into your .env files
-- **AI Access Control** - Block AI from proactively checking or listing your secrets
-- **Universal Compatibility** - Works with any AI tool via multiple protocols
-
-## Platform Compatibility
-
-| Platform | Support | Protocol |
-|----------|---------|----------|
-| Claude Desktop | Native | MCP |
-| Claude Code | Native | MCP |
-| Cursor | Native | MCP |
-| Cline (VS Code) | Native | MCP |
-| Continue.dev | Native | MCP |
-| Zed Editor | Native | MCP |
-| ChatGPT | Via API | OpenAI Function Calling |
-| GPT-4 API | Via API | OpenAI Function Calling |
-| Gemini | Via API | Google Function Calling |
-| Gemini API | Via API | Google Function Calling |
-| Local LLMs (Ollama) | Via API | REST / OpenAI-compatible |
-| LM Studio | Via API | REST / OpenAI-compatible |
-| Open WebUI | Via API | REST |
-| Any HTTP Client | Via API | REST |
-
-## Features
-
-- **Multi-Protocol Support** - MCP, REST API, OpenAI, and Gemini protocols
-- **Auto-Detection** - Automatically detects client type from request headers
-- **AES-256-GCM Encryption** - Military-grade encryption with PBKDF2-SHA512 key derivation
-- **Flexible Passwords** - No complexity requirements - use any password you want
-- **Session Management** - Quick password mode with configurable session duration
-- **AI Access Control** - Prevent AI from actively checking variables without permission
-- **Blacklist Patterns** - Block AI access to sensitive variables matching patterns
-- **Project-based Organization** - Separate environments per project
-- **Auto .env Sync** - Automatically sync to .env files
-- **Audit Logging** - All operations logged for security review
+EnvCP lets you safely use AI assistants (Claude, ChatGPT, Gemini, Cursor, etc.) without exposing your secrets. Your API keys and environment variables stay encrypted on your machine — AI only references them by name.
 
 ## Installation
 
@@ -53,7 +10,7 @@ When using AI coding assistants, you often need to reference environment variabl
 npm install -g envcp
 ```
 
-Or use with npx:
+Or use without installing:
 
 ```bash
 npx envcp init
@@ -61,38 +18,53 @@ npx envcp init
 
 ## Quick Start
 
-### 1. Initialize EnvCP in your project
-
 ```bash
+# 1. Initialize in your project
 envcp init
-```
-
-### 2. Add your secrets
 
-```bash
+# 2. Add your secrets
 envcp add API_KEY --value "your-secret-key"
 envcp add DATABASE_URL --value "postgres://..."
+
+# 3. Start the server (auto-detects client type)
+envcp serve --mode auto --port 3456
 ```
 
-### 3. Start the server
+## Basic CLI Commands
 
 ```bash
-# Auto mode - detects client type automatically (recommended)
-envcp serve --mode auto --port 3456
+# Variable Management
+envcp add <name> [options]    # Add a variable
+envcp list [--show-values]    # List variables
+envcp get <name>              # Get a variable
+envcp remove <name>           # Remove a variable
+
+# Session Management
+envcp unlock                  # Unlock with password
+envcp lock                    # Lock immediately
+envcp status                  # Check session status
 
-# Or specific modes:
-envcp serve --mode mcp       # For Claude Desktop, Cursor, etc.
-envcp serve --mode rest      # For REST API clients
-envcp serve --mode openai    # For ChatGPT/OpenAI-compatible
-envcp serve --mode gemini    # For Google Gemini
-envcp serve --mode all       # All protocols on same port
+# Sync and Export
+envcp sync                    # Sync to .env file
+envcp export [--format env|json|yaml]
 ```
 
+## Why EnvCP?
+
+- **Local-only storage** — Your secrets never leave your machine
+- **Encrypted at rest** — AES-256-GCM with PBKDF2 key derivation (100,000 iterations)
+- **Reference-based access** — AI references variables by name, never sees the actual values
+- **Automatic .env injection** — Values can be automatically injected into your .env files
+- **AI Access Control** — Block AI from proactively listing or checking your secrets
+- **Universal Compatibility** — Works with any AI tool via MCP, OpenAI, Gemini, or REST protocols
+
+---
+
 ## Integration Guides
 
 ### Claude Desktop / Cursor / Cline (MCP)
 
-Add to your config file:
+Add to your MCP config file:
 
 ```json
 {
@@ -107,26 +79,18 @@ Add to your config file:
 
 ### ChatGPT / OpenAI API
 
-Start the server in OpenAI mode:
-
 ```bash
 envcp serve --mode openai --port 3456 --api-key your-secret-key
 ```
 
-Use with OpenAI client:
-
 ```python
 import openai
 
-# Point to EnvCP server
 client = openai.OpenAI(
     base_url="http://localhost:3456/v1",
     api_key="your-secret-key"
 )
 
-# Get available functions
-functions = client.get("/functions")
-
 # Call a function
 result = client.post("/functions/call", json={
     "name": "envcp_get",
@@ -136,14 +100,10 @@ result = client.post("/functions/call", json={
 
 ### Gemini / Google AI
 
-Start the server in Gemini mode:
-
 ```bash
 envcp serve --mode gemini --port 3456 --api-key your-secret-key
 ```
 
-Use with Gemini:
-
 ```python
 import requests
 
@@ -163,22 +123,18 @@ result = requests.post(
 
 ### Local LLMs (Ollama, LM Studio)
 
-For local LLMs, use REST API mode or OpenAI-compatible mode:
-
 ```bash
-# REST API (universal)
-envcp serve --mode rest --port 3456
-
 # OpenAI-compatible (works with most local LLM tools)
 envcp serve --mode openai --port 3456
+
+# Or universal REST
+envcp serve --mode rest --port 3456
 ```
 
-Then configure your LLM tool to use `http://localhost:3456` as the tool server.
+Configure your LLM tool to use `http://localhost:3456` as the tool server.
 
 ### REST API (Universal)
 
-Start the server:
-
 ```bash
 envcp serve --mode rest --port 3456 --api-key your-secret-key
 ```
@@ -198,8 +154,6 @@ GET    /api/tools               - List available tools
 POST   /api/tools/:name         - Call tool by name
 ```
 
-Example:
-
 ```bash
 # List variables
 curl -H "X-API-Key: your-secret-key" http://localhost:3456/api/variables
@@ -218,36 +172,14 @@ curl -X POST -H "X-API-Key: your-secret-key" \
 
 | Mode | Description | Use Case |
 |------|-------------|----------|
+| `auto` | Auto-detect client from headers | Universal (recommended for HTTP) |
 | `mcp` | Model Context Protocol (stdio) | Claude Desktop, Cursor, Cline |
 | `rest` | REST API (HTTP) | Any HTTP client, custom integrations |
 | `openai` | OpenAI function calling format | ChatGPT, GPT-4 API, OpenAI-compatible tools |
 | `gemini` | Google function calling format | Gemini, Google AI |
 | `all` | All HTTP protocols on same port | Multiple clients |
-| `auto` | Auto-detect client from headers | Universal (recommended for HTTP) |
-
-## CLI Commands
 
 ```bash
-# Initialize
-envcp init [options]
-
-# Session Management
-envcp unlock              # Unlock session with password
-envcp lock                # Lock session immediately
-envcp status              # Check session status
-envcp extend [minutes]    # Extend session duration
-
-# Variable Management
-envcp add <name> [options]
-envcp list [--show-values]
-envcp get <name>
-envcp remove <name>
-
-# Sync and Export
-envcp sync                # Sync to .env file
-envcp export [--format env|json|yaml]
-
-# Server
 envcp serve [options]
   --mode, -m      Server mode: mcp, rest, openai, gemini, all, auto
   --port          HTTP port (default: 3456)
@@ -256,9 +188,40 @@ envcp serve [options]
   --password, -p  Encryption password
 ```
 
-## Configuration
+## Platform Compatibility
+
+| Platform | Support | Protocol |
+|----------|---------|----------|
+| Claude Desktop | Native | MCP |
+| Claude Code | Native | MCP |
+| Cursor | Native | MCP |
+| Cline (VS Code) | Native | MCP |
+| Continue.dev | Native | MCP |
+| Zed Editor | Native | MCP |
+| ChatGPT | Via API | OpenAI Function Calling |
+| GPT-4 API | Via API | OpenAI Function Calling |
+| Gemini | Via API | Google Function Calling |
+| Gemini API | Via API | Google Function Calling |
+| Local LLMs (Ollama) | Via API | REST / OpenAI-compatible |
+| LM Studio | Via API | REST / OpenAI-compatible |
+| Open WebUI | Via API | REST |
+| Any HTTP Client | Via API | REST |
 
-### envcp.yaml
+## Available Tools
+
+All protocols expose the same tools:
+
+| Tool | Description |
+|------|-------------|
+| `envcp_list` | List variable names (not values) |
+| `envcp_get` | Get a variable (masked by default) |
+| `envcp_set` | Create/update a variable |
+| `envcp_delete` | Delete a variable |
+| `envcp_sync` | Sync to .env file |
+| `envcp_run` | Run command with env vars injected |
+| `envcp_check_access` | Check if variable is accessible |
+
+## Configuration (envcp.yaml)
 
 ```yaml
 version: "1.0"
@@ -298,20 +261,6 @@ sync:
     - "*_SECRET"
 ```
 
-## Available Tools
-
-All protocols expose the same tools:
-
-| Tool | Description |
-|------|-------------|
-| `envcp_list` | List variable names (not values) |
-| `envcp_get` | Get a variable (masked by default) |
-| `envcp_set` | Create/update a variable |
-| `envcp_delete` | Delete a variable |
-| `envcp_sync` | Sync to .env file |
-| `envcp_run` | Run command with env vars injected |
-| `envcp_check_access` | Check if variable is accessible |
-
 ## AI Access Control
 
 ### Disable Active Checking
@@ -338,7 +287,7 @@ access:
 
 ## Security
 
-### Encryption
+### Encryption Details
 
 - **Cipher**: AES-256-GCM
 - **Key Derivation**: PBKDF2-SHA512 (100,000 iterations)
@@ -364,16 +313,16 @@ Authorization: Bearer your-secret-key
 
 ## Best Practices
 
-1. **Never commit `.envcp/`** - Add to `.gitignore`
-2. **Use API keys for HTTP modes** - Protect your server endpoints
-3. **Disable `allow_ai_active_check`** - Prevent AI from probing for variables
-4. **Use blacklist patterns** - Block sensitive variable patterns
-5. **Use `auto` mode for HTTP** - Let EnvCP detect the client type
-6. **Review access logs** - Check `.envcp/logs/` regularly
+1. **Never commit `.envcp/`** — Add to `.gitignore`
+2. **Use API keys for HTTP modes** — Protect your server endpoints
+3. **Disable `allow_ai_active_check`** — Prevent AI from probing for variables
+4. **Use blacklist patterns** — Block sensitive variable patterns
+5. **Use `auto` mode for HTTP** — Let EnvCP detect the client type
+6. **Review access logs** — Check `.envcp/logs/` regularly
 
 ## License
 
-MIT License - See LICENSE file for details.
+MIT License — See LICENSE file for details.
 
 ## Support
 

package/__tests__/config.test.ts

@@ -0,0 +1,65 @@
+import { matchesPattern, canAccess, isBlacklisted, validateVariableName } from '../src/config/manager';
+import { EnvCPConfigSchema } from '../src/types';
+
+describe('matchesPattern', () => {
+  it('matches exact names', () => {
+    expect(matchesPattern('API_KEY', 'API_KEY')).toBe(true);
+    expect(matchesPattern('API_KEY', 'OTHER')).toBe(false);
+  });
+
+  it('matches wildcard patterns', () => {
+    expect(matchesPattern('DB_SECRET', '*_SECRET')).toBe(true);
+    expect(matchesPattern('DB_KEY', '*_SECRET')).toBe(false);
+    expect(matchesPattern('ADMIN_TOKEN', 'ADMIN_*')).toBe(true);
+  });
+
+  it('does not treat dots as wildcards (regex escaping)', () => {
+    expect(matchesPattern('DB_SECRET', 'DB.SECRET')).toBe(false);
+    expect(matchesPattern('DBXSECRET', 'DB.SECRET')).toBe(false);
+  });
+
+  it('escapes other regex special chars', () => {
+    expect(matchesPattern('A+B', 'A+B')).toBe(true);
+    expect(matchesPattern('AB', 'A+B')).toBe(false);
+    expect(matchesPattern('A?B', 'A?B')).toBe(true);
+    expect(matchesPattern('AB', 'A?B')).toBe(false);
+  });
+});
+
+describe('validateVariableName', () => {
+  it('accepts valid names', () => {
+    expect(validateVariableName('API_KEY')).toBe(true);
+    expect(validateVariableName('_private')).toBe(true);
+    expect(validateVariableName('a')).toBe(true);
+  });
+
+  it('rejects invalid names', () => {
+    expect(validateVariableName('123')).toBe(false);
+    expect(validateVariableName('has space')).toBe(false);
+    expect(validateVariableName('has-dash')).toBe(false);
+    expect(validateVariableName('')).toBe(false);
+  });
+});
+
+describe('canAccess / isBlacklisted', () => {
+  const makeConfig = (overrides: Record<string, unknown> = {}) =>
+    EnvCPConfigSchema.parse({ access: { ...overrides } });
+
+  it('blacklists matching patterns', () => {
+    const config = makeConfig({ blacklist_patterns: ['*_SECRET'] });
+    expect(isBlacklisted('DB_SECRET', config)).toBe(true);
+    expect(isBlacklisted('DB_KEY', config)).toBe(false);
+  });
+
+  it('denies access for denied patterns', () => {
+    const config = makeConfig({ denied_patterns: ['ADMIN_*'] });
+    expect(canAccess('ADMIN_KEY', config)).toBe(false);
+    expect(canAccess('USER_KEY', config)).toBe(true);
+  });
+
+  it('restricts to allowed patterns when set', () => {
+    const config = makeConfig({ allowed_patterns: ['APP_*'] });
+    expect(canAccess('APP_KEY', config)).toBe(true);
+    expect(canAccess('DB_KEY', config)).toBe(false);
+  });
+});

package/__tests__/crypto.test.ts

@@ -0,0 +1,76 @@
+import { encrypt, decrypt, maskValue, validatePassword, quickHash, generateId, generateSessionToken } from '../src/utils/crypto';
+
+describe('encrypt/decrypt', () => {
+  it('round-trips correctly', () => {
+    const text = 'hello world secret';
+    const password = 'test-password-123';
+    const encrypted = encrypt(text, password);
+    expect(encrypted).not.toBe(text);
+    expect(decrypt(encrypted, password)).toBe(text);
+  });
+
+  it('fails with wrong password', () => {
+    const encrypted = encrypt('secret', 'correct');
+    expect(() => decrypt(encrypted, 'wrong')).toThrow();
+  });
+
+  it('produces different ciphertext each time (random salt/iv)', () => {
+    const text = 'same text';
+    const password = 'same password';
+    const a = encrypt(text, password);
+    const b = encrypt(text, password);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('maskValue', () => {
+  it('fully masks short values', () => {
+    expect(maskValue('ab')).toBe('**');
+    expect(maskValue('abcdefgh')).toBe('********');
+  });
+
+  it('shows prefix/suffix for longer values', () => {
+    const result = maskValue('abcdefghijklmnop');
+    expect(result.startsWith('abcd')).toBe(true);
+    expect(result.endsWith('mnop')).toBe(true);
+    expect(result).toContain('*');
+  });
+});
+
+describe('validatePassword', () => {
+  it('accepts valid password with defaults', () => {
+    expect(validatePassword('a', {}).valid).toBe(true);
+  });
+
+  it('rejects too short password', () => {
+    expect(validatePassword('', { min_length: 1 }).valid).toBe(false);
+  });
+
+  it('rejects single char when disallowed', () => {
+    expect(validatePassword('a', { allow_single_char: false }).valid).toBe(false);
+  });
+
+  it('rejects numeric-only when disallowed', () => {
+    expect(validatePassword('1234', { allow_numeric_only: false }).valid).toBe(false);
+  });
+
+  it('enforces complexity', () => {
+    expect(validatePassword('abc', { require_complexity: true }).valid).toBe(false);
+    expect(validatePassword('Abc123!', { require_complexity: true }).valid).toBe(true);
+  });
+});
+
+describe('helpers', () => {
+  it('generateId returns 32-char hex', () => {
+    expect(generateId()).toMatch(/^[a-f0-9]{32}$/);
+  });
+
+  it('generateSessionToken returns 64-char hex', () => {
+    expect(generateSessionToken()).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it('quickHash returns 16-char hex', () => {
+    expect(quickHash('test')).toMatch(/^[a-f0-9]{16}$/);
+    expect(quickHash('test')).toBe(quickHash('test'));
+  });
+});

package/__tests__/http.test.ts

@@ -0,0 +1,49 @@
+import { validateApiKey, RateLimiter } from '../src/utils/http';
+
+describe('validateApiKey', () => {
+  it('returns false for undefined', () => {
+    expect(validateApiKey(undefined, 'expected')).toBe(false);
+  });
+
+  it('returns false for wrong length', () => {
+    expect(validateApiKey('short', 'expected-key')).toBe(false);
+  });
+
+  it('returns false for wrong key', () => {
+    expect(validateApiKey('wrong-key-xx', 'expected-key')).toBe(false);
+  });
+
+  it('returns true for correct key', () => {
+    expect(validateApiKey('my-secret-key', 'my-secret-key')).toBe(true);
+  });
+});
+
+describe('RateLimiter', () => {
+  it('allows requests within limit', () => {
+    const limiter = new RateLimiter(3, 60000);
+    expect(limiter.isAllowed('ip1')).toBe(true);
+    expect(limiter.isAllowed('ip1')).toBe(true);
+    expect(limiter.isAllowed('ip1')).toBe(true);
+  });
+
+  it('blocks requests over limit', () => {
+    const limiter = new RateLimiter(2, 60000);
+    expect(limiter.isAllowed('ip1')).toBe(true);
+    expect(limiter.isAllowed('ip1')).toBe(true);
+    expect(limiter.isAllowed('ip1')).toBe(false);
+  });
+
+  it('tracks IPs independently', () => {
+    const limiter = new RateLimiter(1, 60000);
+    expect(limiter.isAllowed('ip1')).toBe(true);
+    expect(limiter.isAllowed('ip2')).toBe(true);
+    expect(limiter.isAllowed('ip1')).toBe(false);
+  });
+
+  it('reports remaining requests', () => {
+    const limiter = new RateLimiter(3, 60000);
+    expect(limiter.getRemainingRequests('ip1')).toBe(3);
+    limiter.isAllowed('ip1');
+    expect(limiter.getRemainingRequests('ip1')).toBe(2);
+  });
+});

package/__tests__/storage.test.ts

@@ -0,0 +1,94 @@
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import * as os from 'os';
+import { StorageManager } from '../src/storage/index';
+
+describe('StorageManager', () => {
+  let tmpDir: string;
+  let storePath: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'envcp-test-'));
+    storePath = path.join(tmpDir, 'store.enc');
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it('stores and retrieves variables (encrypted)', async () => {
+    const storage = new StorageManager(storePath, true);
+    storage.setPassword('test123');
+
+    await storage.set('API_KEY', {
+      name: 'API_KEY',
+      value: 'secret-value',
+      encrypted: true,
+      created: new Date().toISOString(),
+      updated: new Date().toISOString(),
+      sync_to_env: true,
+    });
+
+    const result = await storage.get('API_KEY');
+    expect(result).toBeDefined();
+    expect(result!.value).toBe('secret-value');
+  });
+
+  it('lists variable names', async () => {
+    const storage = new StorageManager(storePath, true);
+    storage.setPassword('test123');
+
+    const now = new Date().toISOString();
+    await storage.set('A', { name: 'A', value: '1', encrypted: true, created: now, updated: now, sync_to_env: true });
+    await storage.set('B', { name: 'B', value: '2', encrypted: true, created: now, updated: now, sync_to_env: true });
+
+    const names = await storage.list();
+    expect(names.sort()).toEqual(['A', 'B']);
+  });
+
+  it('deletes variables', async () => {
+    const storage = new StorageManager(storePath, true);
+    storage.setPassword('test123');
+
+    const now = new Date().toISOString();
+    await storage.set('X', { name: 'X', value: 'v', encrypted: true, created: now, updated: now, sync_to_env: true });
+
+    expect(await storage.delete('X')).toBe(true);
+    expect(await storage.get('X')).toBeUndefined();
+    expect(await storage.delete('X')).toBe(false);
+  });
+
+  it('returns empty for non-existent store', async () => {
+    const storage = new StorageManager(storePath, true);
+    storage.setPassword('test123');
+
+    const variables = await storage.load();
+    expect(variables).toEqual({});
+  });
+
+  it('fails with wrong password', async () => {
+    const storage = new StorageManager(storePath, true);
+    storage.setPassword('correct');
+
+    const now = new Date().toISOString();
+    await storage.set('KEY', { name: 'KEY', value: 'v', encrypted: true, created: now, updated: now, sync_to_env: true });
+
+    const storage2 = new StorageManager(storePath, true);
+    storage2.setPassword('wrong');
+
+    await expect(storage2.load()).rejects.toThrow('Failed to decrypt');
+  });
+
+  it('uses cache on subsequent loads', async () => {
+    const storage = new StorageManager(storePath, true);
+    storage.setPassword('test123');
+
+    const now = new Date().toISOString();
+    await storage.set('A', { name: 'A', value: '1', encrypted: true, created: now, updated: now, sync_to_env: true });
+
+    // Second load should use cache
+    const v1 = await storage.load();
+    const v2 = await storage.load();
+    expect(v1).toBe(v2); // same reference = cache hit
+  });
+});

package/dist/adapters/base.d.ts

@@ -10,6 +10,7 @@ export declare abstract class BaseAdapter {
     protected tools: Map<string, ToolDefinition>;
     constructor(config: EnvCPConfig, projectPath: string, password?: string);
     protected abstract registerTools(): void;
+    protected registerDefaultTools(): void;
     init(): Promise<void>;
     protected ensurePassword(): Promise<void>;
     getToolDefinitions(): ToolDefinition[];
@@ -60,9 +61,7 @@ export declare abstract class BaseAdapter {
         name: string;
     }): Promise<{
         name: string;
-        exists: boolean;
         accessible: boolean;
-        blacklisted: boolean;
         message: string;
     }>;
     private parseCommand;