no-more-leaked-keys 1.0.0

package/keychain-secrets/workflows/add-mcp.md

@@ -0,0 +1,171 @@
+# Workflow: Add MCP Server Securely
+
+<purpose>
+Securely add an MCP server with authentication to Claude Code or OpenCode WITHOUT exposing the API key. This replaces the unsafe `claude mcp add` command which echoes secrets to the terminal.
+
+**NEVER use `claude mcp add` with `--header "Authorization: Bearer ..."` - it will expose the key!**
+</purpose>
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/keychain-commands.md
+</required_reading>
+
+<process>
+## Step 1: Gather MCP Information
+
+Ask the user for:
+1. **MCP Name** - e.g., `tally`, `github`, `sentry`
+2. **MCP URL** - e.g., `https://api.tally.so/mcp`
+3. **Key Name in Keychain** - e.g., `TALLY_API_KEY` (must already be stored via add-key workflow)
+4. **Target** - `claude` (Claude Code) or `opencode` or `both`
+
+## Step 2: Verify Key Exists in Keychain
+
+```bash
+security find-generic-password -a "$USER" -s "KEY_NAME" -w >/dev/null 2>&1 && \
+echo "[OK] KEY_NAME found in Keychain" || \
+echo "[MISSING] KEY_NAME not in Keychain - add it first with the add-key workflow"
+```
+
+If missing, switch to `add-key.md` workflow first.
+
+## Step 3: Add to Claude Code (~/.claude.json)
+
+**CRITICAL: We directly edit the JSON file. We NEVER echo or print the key.**
+
+Use this Python script to safely add the MCP without exposing the key:
+
+```bash
+python3 << 'PYTHON_SCRIPT'
+import json
+import subprocess
+import os
+
+# Configuration - REPLACE THESE
+MCP_NAME = "MCP_NAME_HERE"
+MCP_URL = "MCP_URL_HERE"
+KEY_NAME = "KEY_NAME_HERE"
+
+# Get key from Keychain (never printed)
+result = subprocess.run(
+    ["security", "find-generic-password", "-a", os.environ["USER"], "-s", KEY_NAME, "-w"],
+    capture_output=True, text=True
+)
+if result.returncode != 0:
+    print(f"[ERROR] Could not retrieve {KEY_NAME} from Keychain")
+    exit(1)
+
+api_key = result.stdout.strip()
+
+# Read existing config
+config_path = os.path.expanduser("~/.claude.json")
+with open(config_path, "r") as f:
+    config = json.load(f)
+
+# Add MCP server
+if "mcpServers" not in config:
+    config["mcpServers"] = {}
+
+config["mcpServers"][MCP_NAME] = {
+    "type": "http",
+    "url": MCP_URL,
+    "headers": {
+        "Authorization": f"Bearer {api_key}"
+    }
+}
+
+# Write back
+with open(config_path, "w") as f:
+    json.dump(config, f, indent=2)
+
+print(f"[SUCCESS] Added {MCP_NAME} MCP to Claude Code")
+print(f"[SUCCESS] Key retrieved from Keychain (never displayed)")
+PYTHON_SCRIPT
+```
+
+## Step 4: Add to OpenCode (~/.config/opencode/opencode.json)
+
+For OpenCode, we can use environment variable syntax which is safer:
+
+```bash
+python3 << 'PYTHON_SCRIPT'
+import json
+import os
+
+# Configuration - REPLACE THESE
+MCP_NAME = "MCP_NAME_HERE"
+MCP_URL = "MCP_URL_HERE"
+KEY_NAME = "KEY_NAME_HERE"
+
+config_path = os.path.expanduser("~/.config/opencode/opencode.json")
+
+# Read existing config
+with open(config_path, "r") as f:
+    config = json.load(f)
+
+# Add MCP server with env var reference (OpenCode expands this at runtime)
+if "mcp" not in config:
+    config["mcp"] = {}
+
+config["mcp"][MCP_NAME] = {
+    "type": "remote",
+    "url": MCP_URL,
+    "enabled": True,
+    "headers": {
+        "Authorization": "Bearer {env:" + KEY_NAME + "}"
+    }
+}
+
+# Write back
+with open(config_path, "w") as f:
+    json.dump(config, f, indent=2)
+
+print(f"[SUCCESS] Added {MCP_NAME} MCP to OpenCode")
+print(f"[SUCCESS] Configured to use {{env:{KEY_NAME}}} (loaded from environment at runtime)")
+PYTHON_SCRIPT
+```
+
+**Note:** OpenCode requires the key to be exported in ~/.zshrc:
+```bash
+grep -q "KEY_NAME" ~/.zshrc || echo 'export KEY_NAME=$(security find-generic-password -a "$USER" -s "KEY_NAME" -w 2>/dev/null)' >> ~/.zshrc
+```
+
+## Step 5: Verify Installation
+
+```bash
+# For Claude Code
+claude mcp list 2>/dev/null | grep -i "MCP_NAME" && echo "[OK] MCP_NAME visible in Claude Code" || echo "[CHECK] Restart Claude Code to see MCP_NAME"
+
+# For OpenCode - just confirm the config exists
+grep -q "MCP_NAME" ~/.config/opencode/opencode.json && echo "[OK] MCP_NAME configured in OpenCode"
+```
+
+## Step 6: Remind User to Restart
+
+Tell the user:
+- "Restart Claude Code / OpenCode for the MCP to be available"
+- "Use `/mcp` to see connected servers"
+- "The API key was pulled from Keychain and written directly to config - it was never displayed"
+</process>
+
+<warning>
+## NEVER DO THIS
+
+```bash
+# UNSAFE - exposes key in terminal output!
+claude mcp add --transport http tally https://api.tally.so/mcp \
+  --header "Authorization: Bearer $(security find-generic-password -a "$USER" -s "TALLY_API_KEY" -w)"
+```
+
+The `claude mcp add` command echoes the full config including headers back to the terminal. Always use this workflow instead.
+</warning>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Key verified in Keychain
+- [ ] MCP config added to target (Claude Code and/or OpenCode)
+- [ ] Key was NEVER echoed to terminal
+- [ ] User reminded to restart their tool
+- [ ] User can verify MCP is connected
+</success_criteria>

package/keychain-secrets/workflows/list-keys.md

@@ -0,0 +1,83 @@
+# Workflow: List Stored Keys
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/keychain-commands.md
+</required_reading>
+
+<process>
+## Step 1: List All Generic Passwords
+
+The `security` command can dump keychain info, but we need to filter for our API keys:
+
+```bash
+# List all generic password entries (shows service names, not values)
+security dump-keychain | grep -A 4 'class: "genp"' | grep '"svce"' | cut -d'"' -f4 | sort -u
+```
+
+This shows the service names (which are our key names like `OPENAI_API_KEY`).
+
+## Step 2: Filter for Common API Keys
+
+Check for commonly used API key names:
+
+```bash
+COMMON_KEYS=(
+    "OPENAI_API_KEY"
+    "ANTHROPIC_API_KEY"
+    "STRIPE_SECRET_KEY"
+    "STRIPE_PUBLISHABLE_KEY"
+    "DATABASE_URL"
+    "SUPABASE_URL"
+    "SUPABASE_ANON_KEY"
+    "SUPABASE_SERVICE_ROLE_KEY"
+    "GITHUB_TOKEN"
+    "VERCEL_TOKEN"
+    "AWS_ACCESS_KEY_ID"
+    "AWS_SECRET_ACCESS_KEY"
+    "GOOGLE_API_KEY"
+    "SENDGRID_API_KEY"
+    "TWILIO_ACCOUNT_SID"
+    "TWILIO_AUTH_TOKEN"
+)
+
+echo "Checking for common API keys in Keychain..."
+echo "==========================================="
+for key in "${COMMON_KEYS[@]}"; do
+    if security find-generic-password -a "$USER" -s "$key" -w >/dev/null 2>&1; then
+        echo "[FOUND] $key"
+    fi
+done
+```
+
+## Step 3: Present Results
+
+Display found keys to the user in a clear format:
+
+```
+Available API Keys in Keychain:
+================================
+[FOUND] OPENAI_API_KEY
+[FOUND] ANTHROPIC_API_KEY
+[FOUND] DATABASE_URL
+
+Not in Keychain (if you need them):
+====================================
+[ ] STRIPE_SECRET_KEY
+[ ] GITHUB_TOKEN
+```
+
+## Step 4: Offer Next Steps
+
+Ask the user:
+1. **Add a missing key** - Switch to add-key.md workflow
+2. **Populate .env** - Switch to populate-env.md workflow
+3. **Done** - Exit skill
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Available keys listed
+- [ ] User can see which keys are stored
+- [ ] User offered next steps
+</success_criteria>

package/keychain-secrets/workflows/populate-env.md

@@ -0,0 +1,128 @@
+# Workflow: Populate .env from Keychain
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/keychain-commands.md
+2. references/env-file-patterns.md
+</required_reading>
+
+<process>
+## Step 1: Identify Required Keys
+
+Ask the user or detect from the project:
+- Check for `.env.example` or `.env.template` in the project
+- Check for environment variable references in code (e.g., `process.env.X`, `os.environ["X"]`)
+- Ask the user what keys the project needs
+
+```bash
+# Check for .env.example
+cat .env.example 2>/dev/null || echo "No .env.example found"
+
+# Search for env var usage
+grep -r "process\.env\." --include="*.js" --include="*.ts" . 2>/dev/null | head -20
+grep -r "os\.environ" --include="*.py" . 2>/dev/null | head -20
+```
+
+## Step 2: Check Keychain for Available Keys
+
+For each required key, check if it exists in Keychain:
+
+```bash
+# Check if a key exists (returns 0 if found, non-zero if not)
+security find-generic-password -a "$USER" -s "KEY_NAME" -w >/dev/null 2>&1 && echo "Found" || echo "Not found"
+```
+
+Report which keys are available and which are missing.
+
+## Step 3: Handle Missing Keys
+
+If keys are missing from Keychain:
+
+1. Ask the user if they want to add the missing keys now
+2. If yes, switch to the `add-key.md` workflow for each missing key
+3. If no, proceed with available keys only (warn about missing ones)
+
+## Step 4: Ensure .gitignore Protection
+
+Before writing .env, verify it's protected:
+
+```bash
+# Check if .gitignore exists and contains .env
+if [ -f .gitignore ]; then
+    grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
+else
+    echo ".env" > .gitignore
+fi
+```
+
+## Step 5: Generate .env File
+
+Write each key to .env by retrieving from Keychain, then secure the file:
+
+```bash
+# Create or overwrite .env
+> .env
+
+# Add each key
+echo "OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w 2>/dev/null)" >> .env
+echo "ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "ANTHROPIC_API_KEY" -w 2>/dev/null)" >> .env
+# ... repeat for each key
+
+# IMPORTANT: Secure file permissions (only owner can read/write)
+chmod 600 .env
+```
+
+**Alternative: Create a reusable script**
+
+```bash
+cat > populate-env.sh << 'EOF'
+#!/bin/bash
+# Populate .env from macOS Keychain
+# Add key names to the KEYS array
+
+KEYS=(
+    "OPENAI_API_KEY"
+    "ANTHROPIC_API_KEY"
+    # Add more keys here
+)
+
+# Ensure .gitignore protection
+[ -f .gitignore ] && grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
+
+> .env
+for key in "${KEYS[@]}"; do
+    value=$(security find-generic-password -a "$USER" -s "$key" -w 2>/dev/null)
+    if [ -n "$value" ]; then
+        echo "$key=$value" >> .env
+        echo "[OK] $key"
+    else
+        echo "[MISSING] $key"
+    fi
+done
+
+# Secure file permissions
+chmod 600 .env
+echo "Done. .env created with secure permissions (600)."
+EOF
+chmod +x populate-env.sh
+```
+
+## Step 6: Verify Success
+
+```bash
+# Count lines in .env (should match expected key count)
+wc -l .env
+
+# Show keys present (values hidden)
+cut -d= -f1 .env
+```
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] All required keys identified
+- [ ] Missing keys reported to user (and optionally added)
+- [ ] .env is in .gitignore
+- [ ] .env file created with keys from Keychain
+- [ ] User can verify which keys were populated
+</success_criteria>

package/keychain-secrets/workflows/remove-key.md

@@ -0,0 +1,71 @@
+# Workflow: Remove Key from Keychain
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/keychain-commands.md
+</required_reading>
+
+<process>
+## Step 1: Confirm Key Name
+
+Ask the user which key they want to remove. Verify it exists first:
+
+```bash
+security find-generic-password -a "$USER" -s "KEY_NAME" -w >/dev/null 2>&1 && \
+echo "Key found: KEY_NAME" || \
+echo "Key not found: KEY_NAME"
+```
+
+## Step 2: Confirm Deletion
+
+**IMPORTANT**: Deletion is permanent. Confirm with the user:
+
+"Are you sure you want to delete KEY_NAME from Keychain? This cannot be undone. You will need to re-add the key if you need it again."
+
+## Step 3: Delete the Key
+
+```bash
+security delete-generic-password -a "$USER" -s "KEY_NAME"
+```
+
+Expected output on success:
+```
+password has been deleted.
+```
+
+## Step 4: Verify Deletion
+
+```bash
+security find-generic-password -a "$USER" -s "KEY_NAME" -w >/dev/null 2>&1 && \
+echo "Error: Key still exists" || \
+echo "Confirmed: KEY_NAME has been removed"
+```
+
+## Step 5: Update .env if Needed
+
+If a .env file exists and contains this key, warn the user:
+
+```bash
+if [ -f .env ] && grep -q "KEY_NAME=" .env; then
+    echo "Warning: .env still contains KEY_NAME"
+    echo "You may want to regenerate .env or remove this line"
+fi
+```
+
+## Step 6: Offer Next Steps
+
+Ask the user:
+1. **Remove another key** - Repeat this workflow
+2. **Re-add this key** - Switch to add-key.md workflow
+3. **Update .env** - Switch to populate-env.md workflow
+4. **Done** - Exit skill
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Key existence confirmed
+- [ ] User confirmed deletion
+- [ ] Key deleted from Keychain
+- [ ] Deletion verified
+- [ ] User warned about .env if applicable
+</success_criteria>

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "no-more-leaked-keys",
+  "version": "1.0.0",
+  "description": "Stop accidentally exposing API keys. Secure key management for Claude Code using macOS Keychain.",
+  "bin": {
+    "no-more-leaked-keys": "./bin/install.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/install.js"
+  },
+  "keywords": [
+    "api-keys",
+    "security",
+    "secrets",
+    "keychain",
+    "macos",
+    "claude",
+    "claude-code",
+    "opencode",
+    "dotenv",
+    "env",
+    "environment-variables",
+    "mcp",
+    "credentials",
+    "secret-management"
+  ],
+  "author": "Andrew Naegele",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vibe-Marketer/no-more-leaked-keys.git"
+  },
+  "homepage": "https://github.com/Vibe-Marketer/no-more-leaked-keys#readme",
+  "bugs": {
+    "url": "https://github.com/Vibe-Marketer/no-more-leaked-keys/issues"
+  },
+  "os": ["darwin"],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "keychain-secrets/",
+    "commands/",
+    "hooks/",
+    "LICENSE",
+    "README.md"
+  ]
+}