humanenv 0.1.0

package/README.md

@@ -0,0 +1,303 @@
+# humanenv
+
+Securely inject environment variables into your application so that AI agents and non-human consumers **cannot access secrets directly**. The server is the single source of truth. Secrets are encrypted at rest and exist in memory only when explicitly requested.
+
+## Core Idea
+
+Instead of storing `.env` files that every process can read, `humanenv` sits between your app and its secrets. Clients connect via WebSocket, authenticate with a per-project API key + device fingerprint, retrieve individual values, use them, and null them out. No bulk dump possible.
+
+## Architecture
+
+```
+humanenv (client) ──[WS:port]── humanenv-server ──[SQLite/MongoDB]── encrypted envs
+     │                             │
+     ├─ JS SDK ── your app ────────┤
+     ├─ CLI ── terminal ───────────┤
+     └─ .agents/skills/ ── AI agents read skill, use humanenv.get()
+
+humanenv-server ──[HTTP:port]── Admin UI (Vue3 SPA)
+```
+
+## Quick Start
+
+### 1. Start the Server
+
+Run directly from source (after `npm install`):
+
+```bash
+# From the monorepo root
+npx tsx packages/server/src/index.ts --port 3056 --basicAuth
+```
+
+Or after building:
+```bash
+node packages/server/dist/index.js --port 3056 --basicAuth
+```
+
+Flags:
+- `--port <number>` — override default 3056 (also supports `PORT` env)
+- `--basicAuth` — require HTTP Basic Auth for admin UI (reads `BASIC_AUTH_USERNAME`/`BASIC_AUTH_PASSWORD`, falls back to `admin/admin`)
+- `MONGODB_URI=<uri>` — use MongoDB instead of SQLite
+
+### 2. First-Time Admin Setup
+
+1. Open `http://localhost:3056` in your browser
+2. If `HUMANENV_MNEMONIC` env var is **not set**, the UI prompts you to generate or paste a 12-word recovery phrase
+3. **Save the phrase securely** — it is never stored. Losing it means all encrypted data is unrecoverable
+4. Create your first project
+
+### 3. Create a Project & API Key
+
+In the Admin UI:
+1. Create a project (e.g., `my-app`)
+2. Under **API Keys**, generate a new key
+3. Copy the plain API key — it will not be shown again
+
+### 4. Authenticate the CLI
+
+```bash
+# Set up credentials
+npx tsx packages/cli/src/bin.js auth \
+  --project-name my-app \
+  --server-url http://localhost:3056 \
+  --api-key <your-api-key>
+```
+
+This stores credentials at `~/.humanenv/credentials.json`.
+
+### 5. Retrieve a Secret
+
+```bash
+npx tsx packages/cli/src/bin.js get API_KEY
+# Outputs: sk-proj-xxxxxxxxxxxx
+```
+
+### 6. Use in Your Application
+
+```javascript
+import humanenv from 'humanenv'
+
+humanenv.config({
+  serverUrl: 'http://localhost:3056',
+  projectName: 'my-app',
+  projectApiKey: 'your-api-key',
+})
+
+// Single key
+let apiKey = await humanenv.get('API_KEY')
+someLib.use(apiKey)
+apiKey = null  // always null after use
+
+// Multiple keys at once
+let { API_KEY, DATABASE_URL } = await humanenv.get(['API_KEY', 'DATABASE_URL'])
+db.connect(DATABASE_URL)
+DATABASE_URL = null
+API_KEY = null
+
+// Set/unset secrets at runtime
+await humanenv.set('API_KEY', 'new-value')
+```
+
+CommonJS compatible:
+```javascript
+const humanenv = require('humanenv').default
+```
+
+## CLI Reference
+
+Commands:
+
+```bash
+humanenv                        # Auto-generate .agents/skills/humanenv-usage/SKILL.md
+                                # Outputs skill to stdout if non-TTY (for agents)
+                                # Outputs help if TTY (for humans)
+
+humanenv auth --project-name <name> --server-url <url> [--api-key <key>]
+                                # Authenticate with the server
+
+humanenv get <key>              # Retrieve an env value
+humanenv set <key> <value>      # Update or create an env value
+
+humanenv server [--port 3056] [--basicAuth]
+                                # Start the server in-process
+```
+
+### Skill Auto-Generation
+
+Running `humanenv` without arguments creates `.agents/skills/humanenv-usage/SKILL.md` in the current directory. This skill teaches AI agents how to use humanenv correctly:
+- Never log or dump sensitive values
+- Always null variables after use
+- Never write secrets to files
+- Use `humanenv.get('key')` individually
+
+## Security Model
+
+### Encryption at Rest
+
+All env values are encrypted with AES-256-GCM before persistence. The encryption key (PK) is derived from a BIP39 12-word mnemonic using PBKDF2 (SHA-256, 100k iterations).
+
+The PK **never touches disk**. Only a SHA-256 hash of the PK is stored in the database for verification.
+
+### Zero-Touch Restarts via HUMANENV_MNEMONIC
+
+For production use (Docker, K8s, CI), set the mnemonic as an environment variable:
+
+```bash
+HUMANENV_MNEMONIC="word1 word2 word3 ... word12" humanenv server
+```
+
+The PK is derived on startup — no manual entry required. If the env var is **not set**, the server blocks client requests and waits for admin input via the UI.
+
+### Client Authentication
+
+Each client authenticates with:
+1. **Project name** — must exist on the server
+2. **API key** — per-project secret (encrypted at rest)
+3. **Fingerprint** — deterministic hash of hostname + platform + arch + Node version
+
+Clients must be **whitelisted** by an admin before they can retrieve secrets. New clients send a pending request visible in real-time in the Admin UI.
+
+### API-Mode Only Envs
+
+Secrets can be flagged as **api-mode only**. These are accessible only via the WebSocket SDK (your app), not via the CLI. Non-human agents cannot bypass this: the CLI enforces the gate.
+
+### Threat Matrix
+
+| Scenario | Mitigation |
+|---|---|
+| Agent reads .env files | No .env files exist |
+| Agent logs env values | Skill instructs against it; SDK does not auto-log |
+| Database dump leaked | All values encrypted; PK not in database |
+| Server restart | PK from env var or manual admin re-entry |
+| Rogue client connects | Fingerprint + API key + whitelist required |
+| Memory dump | Developer must null values after use |
+
+## Server Configuration
+
+### Ports & Auth
+
+```bash
+# Environment variables
+PORT=3056                           # Server port
+BASIC_AUTH_USERNAME=admin           # Admin UI username
+BASIC_AUTH_PASSWORD=secret          # Admin UI password
+
+# Flags
+--port 3056                         # Override PORT
+--basicAuth                         # Enable basic auth for admin UI
+```
+
+### Database
+
+**SQLite (default):**
+```bash
+# Uses ~/.humanenv/humanenv.db automatically
+```
+
+**MongoDB:**
+```bash
+MONGODB_URI="mongodb://localhost:27017" npx tsx packages/server/src/index.ts
+```
+
+MongoDB connection failure at bootstrap falls back to SQLite with a warning. Runtime MongoDB disconnections trigger infinite retry with 10-second delays.
+
+### Data Directory
+
+All persistent data (SQLite DB, credentials) lives in `~/.humanenv/` by default.
+
+## Admin UI
+
+Access at `http://localhost:<PORT>`.
+
+### Dashboard
+- Create/delete projects
+- View project list with creation timestamps
+
+### Per-Project Management
+
+**Envs Tab:**
+- Add key-value pairs
+- Toggle "api-mode-only" flag per env
+- Update or delete existing envs
+
+**API Keys Tab:**
+- Generate new keys (with optional TTL in seconds)
+- Revoke/rotate existing keys
+- Toggle auto-accept for client API key generation requests
+
+**Whitelist Tab:**
+- Add approved fingerprints manually
+- Review pending requests from unknown clients
+- Accept or reject in real-time
+
+**Real-Time Notifications:**
+Toast notifications appear when:
+- A new client sends a whitelist request
+- A client requests API key generation
+
+## Project Structure
+
+```
+packages/
+  shared/             # Shared types, crypto utilities, error codes
+    src/
+      crypto.ts       # AES-256-GCM, PBKDF2, BIP39 mnemonic, fingerprints
+      errors.ts       # ErrorCode enum and HumanEnvError class
+      types.ts        # Interfaces + SKILL_CONTENT template
+      index.ts        # Re-exports
+  server/             # Express + WebSocket server + Admin UI
+    src/
+      index.ts        # Server entry, Express setup, route wiring
+      pk-manager.ts   # Private key lifecycle (derive, verify, encrypt, decrypt)
+      auth.ts         # HTTP Basic Auth middleware
+      db/
+        interface.ts  # IDatabaseProvider interface
+        sqlite.ts     # better-sqlite3 implementation
+        mongo.ts      # MongoDB (native driver) implementation
+        index.ts      # Factory: try Mongo, fallback to SQLite
+      routes/
+        index.ts      # REST endpoints: projects, envs, api keys, whitelist
+      ws/
+        router.ts     # WebSocket handler: client SDK + admin UI channels
+      views/
+        index.ejs     # Admin UI (Vue3, Tailwind, DaisyUI via CDN)
+  client/             # npm package (humanenv) — SDK for apps
+    src/
+      index.ts        # Main API: config(), get(), set(), disconnect()
+      ws-manager.ts   # WebSocket connection, auth, auto-reconnect
+  cli/               # CLI tool
+    src/
+      bin.js          # commander CLI: auth, get, set, server
+```
+
+## Error Codes
+
+| Code | Description |
+|---|---|
+| `SERVER_PK_NOT_AVAILABLE` | Server has no PK in memory; admin must provide mnemonic |
+| `CLIENT_AUTH_INVALID_PROJECT_NAME` | Project name does not exist |
+| `CLIENT_AUTH_NOT_WHITELISTED` | Client fingerprint not approved |
+| `CLIENT_AUTH_INVALID_API_KEY` | API key is invalid or expired |
+| `CLIENT_CONN_MAX_RETRIES_EXCEEDED` | WS reconnection limit reached |
+| `ENV_API_MODE_ONLY` | Env flagged as API-mode only; CLI access denied |
+
+## Development
+
+```bash
+npm install                     # Monorepo install (workspaces)
+
+# Start server (dev)
+cd packages/server && npx tsx src/index.ts
+
+# Start CLI (dev)
+cd packages/cli && node src/bin.js get MY_KEY
+
+# Type check
+npx tsc --noEmit -p packages/server
+npx tsc --noEmit -p packages/client
+npx tsc --noEmit -p packages/shared
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "humanenv",
+  "version": "0.1.0",
+  "description": "Securely inject environment variables into your app. Secrets for humans only.",
+  "author": "arancibiajav@gmail.com",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:javimosch/humanenv.git"
+  },
+  "license": "MIT",
+  "workspaces": [
+    "packages/shared",
+    "packages/server",
+    "packages/client",
+    "packages/cli"
+  ],
+  "bin": {
+    "humanenv": "packages/client/dist/cli.js"
+  },
+  "scripts": {
+    "build": "npm run build --workspaces --if-present",
+    "server": "npm run dev --workspace=packages/server",
+    "cli": "node packages/cli/src/bin.js",
+    "test": "node --import tsx --test packages/*/tests/*.test.ts",
+    "test:shared": "node --import tsx --test packages/shared/tests/*.test.ts",
+    "test:server": "node --import tsx --test packages/server/tests/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/basic-auth": "^1.1.8",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/ejs": "^3.1.5",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0"
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "humanenv-cli",
+  "version": "0.1.0",
+  "private": true,
+  "bin": {
+    "humanenv": "./src/bin.js"
+  },
+  "scripts": {
+    "dev": "node src/bin.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "humanenv-shared": "file:../shared"
+  }
+}

package/packages/cli/src/bin.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+const { Command } = require('commander')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { generateFingerprint, SKILL_CONTENT } = require('humanenv-shared')
+
+const program = new Command()
+const CREDENTIALS_DIR = path.join(os.homedir(), '.humanenv')
+
+function ensureCredentialsDir() {
+  if (!fs.existsSync(CREDENTIALS_DIR)) fs.mkdirSync(CREDENTIALS_DIR, { recursive: true })
+}
+
+function readCredentials() {
+  const p = path.join(CREDENTIALS_DIR, 'credentials.json')
+  if (!fs.existsSync(p)) return null
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')) } catch { return null }
+}
+
+function writeCredentials(data) {
+  ensureCredentialsDir()
+  fs.writeFileSync(path.join(CREDENTIALS_DIR, 'credentials.json'), JSON.stringify(data, null, 2), 'utf8')
+}
+
+function ensureSkillFile() {
+  const skillPath = path.join(process.cwd(), '.agents', 'skills', 'humanenv-usage', 'SKILL.md')
+  if (!fs.existsSync(skillPath)) {
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true })
+    fs.writeFileSync(skillPath, SKILL_CONTENT, 'utf8')
+    if (process.stdout.isTTY) console.log('Generated .agents/skills/humanenv-usage/SKILL.md')
+  }
+}
+
+// ============================================================
+// Main entry: humanenv (no args)
+// ============================================================
+
+program
+  .action(() => {
+    ensureSkillFile()
+    if (!process.stdout.isTTY) {
+      // Non-TTY: output skill content for agents
+      const skillPath = path.join(process.cwd(), '.agents', 'skills', 'humanenv-usage', 'SKILL.md')
+      console.log(fs.readFileSync(skillPath, 'utf8'))
+    } else {
+      // TTY: show human-friendly help
+      console.log('HumanEnv - Secure environment variable injection')
+      console.log('')
+      console.log('Usage:')
+      console.log('  humanenv auth --project-name <name> --server-url <url> [--api-key <key>]')
+      console.log('  humanenv auth --project-name <name> --server-url <url> --generate-api-key')
+      console.log('  humanenv get <key>')
+      console.log('  humanenv set <key> <value>')
+      console.log('  humanenv server [--port 3056] [--basicAuth]')
+      console.log('')
+    }
+  })
+
+// ============================================================
+// Auth command
+// ============================================================
+
+program
+  .command('auth')
+  .option('--project-name <name>')
+  .option('--server-url <url>')
+  .option('--api-key <key>')
+  .option('--generate-api-key', false)
+  .action(async (opts) => {
+    ensureSkillFile()
+    if (!opts.projectName || !opts.serverUrl) {
+      console.error('Error: --project-name and --server-url required')
+      process.exit(1)
+    }
+
+    const creds = {
+      projectName: opts.projectName,
+      serverUrl: opts.serverUrl,
+      apiKey: opts.apiKey || undefined,
+    }
+    writeCredentials(creds)
+
+    if (opts.generateApiKey) {
+      const { HumanEnvClient } = require('humanenv/dist/ws-manager')
+      const client = new HumanEnvClient({
+        serverUrl: opts.serverUrl,
+        projectName: opts.projectName,
+        projectApiKey: opts.apiKey || '',
+        maxRetries: 3,
+      })
+
+      try {
+        await client.connect()
+        const result = await new Promise((resolve, reject) => {
+          client.disconnect()
+          // For CLI generate-api-key, we use a simple HTTP call instead
+          // since WS API key generation is complex
+          resolve(null)
+        })
+        console.log('API key generation request sent. Admin must approve in dashboard.')
+      } catch (e) {
+        console.error('Failed to connect:', e.message)
+        process.exit(1)
+      }
+    } else {
+      // Verify credentials by connecting
+      const { HumanEnvClient } = require('humanenv/dist/ws-manager')
+      const client = new HumanEnvClient({
+        serverUrl: opts.serverUrl,
+        projectName: opts.projectName,
+        projectApiKey: opts.apiKey || '',
+        maxRetries: 3,
+      })
+
+      try {
+        await client.connect()
+        console.log('Authenticated successfully.')
+        client.disconnect()
+      } catch (e) {
+        console.error('Auth failed:', e.message)
+        process.exit(1)
+      }
+    }
+
+    console.log('Credentials stored in', path.join(CREDENTIALS_DIR, 'credentials.json'))
+  })
+
+// ============================================================
+// Get command
+// ============================================================
+
+program
+  .command('get')
+  .argument('<key>', 'Environment variable key')
+  .action(async (key) => {
+    const creds = readCredentials()
+    if (!creds) {
+      console.error('Error: Not authenticated. Run: humanenv auth --project-name <name> --server-url <url>')
+      process.exit(1)
+    }
+
+    const { HumanEnvClient } = require('humanenv/dist/ws-manager')
+    const client = new HumanEnvClient({
+      serverUrl: creds.serverUrl,
+      projectName: creds.projectName,
+      projectApiKey: creds.apiKey || '',
+      maxRetries: 3,
+    })
+
+    try {
+      await client.connect()
+      const value = await client.get(key)
+      // Non-TTY: output raw value only
+      if (!process.stdout.isTTY) {
+        process.stdout.write(value)
+      } else {
+        console.log(value)
+      }
+      client.disconnect()
+    } catch (e) {
+      console.error('Failed to get env:', e.message)
+      process.exit(1)
+    }
+  })
+
+// ============================================================
+// Set command
+// ============================================================
+
+program
+  .command('set')
+  .argument('<key>', 'Environment variable key')
+  .argument('<value>', 'Environment variable value')
+  .action(async (key, value) => {
+    const creds = readCredentials()
+    if (!creds) {
+      console.error('Error: Not authenticated. Run: humanenv auth --project-name <name> --server-url <url>')
+      process.exit(1)
+    }
+
+    const { HumanEnvClient } = require('humanenv/dist/ws-manager')
+    const client = new HumanEnvClient({
+      serverUrl: creds.serverUrl,
+      projectName: creds.projectName,
+      projectApiKey: creds.apiKey || '',
+      maxRetries: 3,
+    })
+
+    try {
+      await client.connect()
+      await client.set(key, value)
+      console.log('Set', key)
+      client.disconnect()
+    } catch (e) {
+      console.error('Failed to set env:', e.message)
+      process.exit(1)
+    }
+  })
+
+// ============================================================
+// Server command (delegates to server package)
+// ============================================================
+
+program
+  .command('server')
+  .option('--port <number>')
+  .option('--basicAuth', false)
+  .action((opts) => {
+    const portArg = opts.port ? `--port=${opts.port}` : ''
+    const basicAuthArg = opts.basicAuth ? '--basicAuth' : ''
+    const serverPath = path.join(__dirname, '..', '..', 'server', 'src', 'index.ts')
+    const serverJs = fs.existsSync(path.join(__dirname, '..', '..', 'server', 'dist', 'index.js'))
+      ? path.join(__dirname, '..', '..', 'server', 'dist', 'index.js')
+      : null
+
+    if (serverJs && fs.existsSync(serverJs)) {
+      require('child_process').fork(serverJs, [portArg, basicAuthArg].filter(Boolean), { stdio: 'inherit' })
+    } else {
+      // Fallback: run via tsx
+      const { spawn } = require('child_process')
+      const args = [serverPath, portArg, basicAuthArg].filter(Boolean)
+      const child = spawn('npx', ['tsx', ...args], { stdio: 'inherit', shell: process.platform === 'win32' })
+      child.on('close', (code) => process.exit(code))
+    }
+  })
+
+program.parse(process.argv)