no-more-leaked-keys 1.0.0

package/hooks/block-unsafe-mcp-add.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Hook: Block unsafe 'claude mcp add' commands that would expose API keys
+# Installed by: no-more-leaked-keys skill
+
+# This hook is triggered by Claude Code's PreToolUse event
+# It checks if the command contains 'claude mcp add' with auth headers
+
+INPUT=$(cat)
+
+# Check if this is a Bash command containing unsafe mcp add
+if echo "$INPUT" | grep -q "claude mcp add" && echo "$INPUT" | grep -qi "header.*authorization\|header.*bearer"; then
+    echo '{"decision": "block", "message": "BLOCKED: claude mcp add with auth headers exposes your API key in terminal output!\n\nUse /secrets or /add-mcp instead - these pull keys from Keychain securely without exposing them.\n\nSee: https://github.com/Vibe-Marketer/no-more-leaked-keys"}'
+    exit 0
+fi
+
+# Allow all other commands
+echo '{"decision": "allow"}'

package/keychain-secrets/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: keychain-secrets
+description: "Securely manage API keys using macOS Keychain. Use when working with .env files, adding new API keys, adding MCP servers, or populating environment variables from Keychain. Triggers on: api key, keychain, .env, environment variables, secrets, credentials, mcp, mcp server, claude mcp add."
+---
+
+<essential_principles>
+## Security-First API Key Management
+
+This skill uses macOS Keychain to securely store and retrieve API keys. Keys are never stored in plain text, never committed to git, and never exposed on screen during input.
+
+### Principle 1: Keychain is the Source of Truth
+
+API keys live in Keychain, not in files. The `.env` file is populated at runtime from Keychain. This means:
+- Keys are encrypted at rest by macOS
+- Keys can be used across any project on your machine
+- Accidental exposure via git or screen share is impossible
+
+### Principle 2: Safe Input for New Keys
+
+When adding keys to Keychain, we use `read -s` to prevent the key from appearing on screen. The key is passed directly to the `security` command without echoing.
+
+### Principle 3: .env Files are Ephemeral
+
+The `.env` file should be in `.gitignore` and can be regenerated anytime from Keychain. Never edit `.env` directly with secrets - always add to Keychain first.
+
+### Key Naming Convention
+
+Use SCREAMING_SNAKE_CASE that matches the environment variable name:
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `STRIPE_SECRET_KEY`
+- `DATABASE_URL`
+</essential_principles>
+
+<intake>
+What would you like to do?
+
+1. **Populate .env from Keychain** - Retrieve stored keys and write them to a .env file
+2. **Add a new key to Keychain** - Securely store a new API key (won't appear on screen)
+3. **Add MCP server securely** - Add an MCP to Claude Code or OpenCode WITHOUT exposing keys
+4. **List stored keys** - See what keys are available in your Keychain
+5. **Remove a key** - Delete a key from Keychain
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "populate", "env", "retrieve", "get", "write env" | `workflows/populate-env.md` |
+| 2, "add", "store", "new key", "save" | `workflows/add-key.md` |
+| 3, "mcp", "add mcp", "claude mcp", "opencode mcp" | `workflows/add-mcp.md` |
+| 4, "list", "show", "available", "what keys" | `workflows/list-keys.md` |
+| 5, "remove", "delete", "revoke" | `workflows/remove-key.md` |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<critical_warning>
+## NEVER USE `claude mcp add` WITH AUTH HEADERS
+
+The `claude mcp add` command **exposes secrets in terminal output**:
+
+```bash
+# DANGEROUS - This will print your API key to the terminal!
+claude mcp add --transport http tally https://api.tally.so/mcp \
+  --header "Authorization: Bearer $TALLY_API_KEY"
+```
+
+**Always use option 3 (Add MCP server securely) instead.** This workflow:
+- Pulls the key from Keychain silently
+- Writes directly to config files
+- Never echoes the key anywhere
+</critical_warning>
+
+<reference_index>
+All domain knowledge in `references/`:
+
+**Commands:** keychain-commands.md - All macOS security CLI patterns
+**Env Files:** env-file-patterns.md - Safe .env file handling
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| populate-env.md | Retrieve keys from Keychain and write to .env |
+| add-key.md | Securely add a new API key to Keychain |
+| add-mcp.md | Securely add MCP server to Claude Code / OpenCode |
+| list-keys.md | Show available keys in Keychain |
+| remove-key.md | Delete a key from Keychain |
+</workflows_index>
+
+<quick_commands>
+## Quick Reference
+
+**Add key (Claude runs this - you just paste):**
+```bash
+read -s -p "Paste API key: " K && security add-generic-password -a "$USER" -s "KEY_NAME" -w "$K" && unset K && pbcopy < /dev/null && echo -e "\n[OK] Stored"
+```
+
+**Retrieve key:**
+```bash
+security find-generic-password -a "$USER" -s "KEY_NAME" -w
+```
+
+**Delete key:**
+```bash
+security delete-generic-password -a "$USER" -s "KEY_NAME"
+```
+
+**Populate .env from Keychain:**
+```bash
+echo "OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w 2>/dev/null)" >> .env && chmod 600 .env
+```
+</quick_commands>
+
+<security_measures>
+## Security Measures
+
+This skill implements multiple layers of protection:
+
+1. **Silent input** - Keys never appear on screen when you paste
+2. **Memory cleanup** - Variables cleared immediately after use
+3. **Clipboard clearing** - Auto-clears clipboard after storing key
+4. **Encrypted storage** - macOS Keychain uses AES-256 encryption
+5. **File permissions** - .env created with 600 permissions (owner only)
+6. **Git protection** - Automatically adds .env to .gitignore
+7. **No logging** - Keys never written to terminal history
+</security_measures>

package/keychain-secrets/references/env-file-patterns.md

@@ -0,0 +1,220 @@
+# .env File Patterns Reference
+
+<overview>
+Safe patterns for working with .env files when using Keychain as the source of truth.
+</overview>
+
+<gitignore_protection>
+## Always Protect .env
+
+Before creating any .env file, ensure it's in .gitignore:
+
+```bash
+# Check if .gitignore exists and has .env
+if [ -f .gitignore ]; then
+    grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
+else
+    echo ".env" > .gitignore
+fi
+```
+
+Also consider ignoring:
+```
+.env
+.env.local
+.env.*.local
+*.env
+```
+</gitignore_protection>
+
+<env_file_format>
+## .env File Format
+
+Standard format:
+```bash
+KEY_NAME=value
+ANOTHER_KEY=another_value
+```
+
+Rules:
+- No spaces around `=`
+- No quotes needed for simple values
+- Use quotes for values with spaces: `KEY="value with spaces"`
+- Comments start with `#`
+- Blank lines are ignored
+</env_file_format>
+
+<generation_patterns>
+## Generating .env from Keychain
+
+### Simple Generation
+```bash
+> .env  # Clear/create file
+echo "OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w)" >> .env
+echo "DATABASE_URL=$(security find-generic-password -a "$USER" -s "DATABASE_URL" -w)" >> .env
+```
+
+### With Error Handling
+```bash
+add_key_to_env() {
+    local key=$1
+    local value=$(security find-generic-password -a "$USER" -s "$key" -w 2>/dev/null)
+    if [ -n "$value" ]; then
+        echo "$key=$value" >> .env
+        echo "Added $key"
+    else
+        echo "# $key not found in Keychain" >> .env
+        echo "Warning: $key not found"
+    fi
+}
+
+> .env
+add_key_to_env "OPENAI_API_KEY"
+add_key_to_env "DATABASE_URL"
+```
+
+### Reusable Script (populate-env.sh)
+```bash
+#!/bin/bash
+# populate-env.sh - Generate .env from Keychain
+
+KEYS=(
+    "OPENAI_API_KEY"
+    "ANTHROPIC_API_KEY"
+    "DATABASE_URL"
+    # Add your keys here
+)
+
+# Ensure .gitignore protection
+if [ -f .gitignore ]; then
+    grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
+else
+    echo ".env" > .gitignore
+fi
+
+# Generate .env
+> .env
+found=0
+missing=0
+
+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
+        ((found++))
+    else
+        echo "# $key - NOT FOUND" >> .env
+        ((missing++))
+    fi
+done
+
+echo "Generated .env: $found keys found, $missing missing"
+```
+</generation_patterns>
+
+<project_templates>
+## .env.example Template
+
+Create a .env.example that documents required keys without values:
+
+```bash
+# .env.example - Required environment variables
+# Copy to .env and populate from Keychain: ./populate-env.sh
+
+# OpenAI API
+OPENAI_API_KEY=
+
+# Anthropic API
+ANTHROPIC_API_KEY=
+
+# Database
+DATABASE_URL=
+
+# Stripe (if using payments)
+STRIPE_SECRET_KEY=
+STRIPE_PUBLISHABLE_KEY=
+```
+
+This file IS committed to git (no secrets) and documents what the project needs.
+</project_templates>
+
+<verification>
+## Verifying .env
+
+### Check Keys Present (values hidden)
+```bash
+cut -d= -f1 .env | grep -v "^#" | grep -v "^$"
+```
+
+### Count Keys
+```bash
+grep -c "=" .env
+```
+
+### Check for Empty Values
+```bash
+grep "=$" .env  # Lines ending with = have no value
+```
+
+### Validate Format
+```bash
+# Lines should match: KEY=value or be comments/blank
+grep -v "^#" .env | grep -v "^$" | grep -v "^[A-Z_]*=" && echo "Invalid lines found" || echo "Format OK"
+```
+</verification>
+
+<framework_loading>
+## Framework-Specific Loading
+
+### Node.js (dotenv)
+```javascript
+require('dotenv').config();
+// or in ES modules:
+import 'dotenv/config';
+```
+
+### Python (python-dotenv)
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+### Next.js
+Automatic - .env.local is loaded by default.
+
+### Vite
+Automatic - .env files are loaded. Use `VITE_` prefix for client-side vars.
+</framework_loading>
+
+<security_reminders>
+## Security Reminders
+
+1. **Never commit .env** - Always in .gitignore
+2. **Never log env vars** - Don't `console.log(process.env)`
+3. **Never expose in client code** - Only use server-side
+4. **Regenerate, don't edit** - If you need to change keys, update Keychain and regenerate .env
+5. **.env.example is safe** - Commit it to document required vars (no values)
+6. **Set file permissions** - Always `chmod 600 .env` (owner read/write only)
+7. **Clear clipboard** - After pasting keys, clipboard is auto-cleared to prevent accidents
+</security_reminders>
+
+<file_permissions>
+## Securing .env File Permissions
+
+After creating .env, always set restrictive permissions:
+
+```bash
+chmod 600 .env
+```
+
+This means:
+- Owner can read and write (you)
+- Group has no access
+- Others have no access
+
+Verify with:
+```bash
+ls -la .env
+# Should show: -rw-------
+```
+</file_permissions>

package/keychain-secrets/references/keychain-commands.md

@@ -0,0 +1,159 @@
+# macOS Keychain Security Commands Reference
+
+<overview>
+macOS provides the `security` CLI tool to interact with Keychain from the terminal. This reference covers all commands needed for API key management.
+</overview>
+
+<command_reference>
+## Core Commands
+
+### Add a Password
+```bash
+security add-generic-password -a "$USER" -s "SERVICE_NAME" -w "PASSWORD"
+```
+
+Parameters:
+- `-a` : Account name (use `$USER` for current user)
+- `-s` : Service name (the key identifier, e.g., `OPENAI_API_KEY`)
+- `-w` : Password/secret value
+
+**Will fail if key already exists.** Delete first to update.
+
+### Retrieve a Password
+```bash
+security find-generic-password -a "$USER" -s "SERVICE_NAME" -w
+```
+
+Parameters:
+- `-a` : Account name
+- `-s` : Service name
+- `-w` : Output only the password (not metadata)
+
+Returns just the password value. Exit code 0 on success, non-zero if not found.
+
+### Delete a Password
+```bash
+security delete-generic-password -a "$USER" -s "SERVICE_NAME"
+```
+
+Removes the entry from Keychain. Cannot be undone.
+
+### Check if Password Exists
+```bash
+security find-generic-password -a "$USER" -s "SERVICE_NAME" -w >/dev/null 2>&1
+echo $?  # 0 = exists, non-zero = not found
+```
+
+### List All Entries
+```bash
+# List all generic passwords (shows metadata, not values)
+security dump-keychain | grep -A 4 'class: "genp"'
+
+# Extract just service names
+security dump-keychain | grep -A 4 'class: "genp"' | grep '"svce"' | cut -d'"' -f4 | sort -u
+```
+</command_reference>
+
+<secure_patterns>
+## Secure Input Patterns
+
+### Silent Input with Clipboard Clear (Recommended)
+```bash
+read -s -p "Paste value: " VALUE && \
+security add-generic-password -a "$USER" -s "KEY_NAME" -w "$VALUE" && \
+unset VALUE && \
+pbcopy < /dev/null && \
+echo -e "\n[OK] Stored + clipboard cleared"
+```
+
+- `read -s` : Silent mode (no echo to screen)
+- `unset VALUE` : Clear from shell memory after use
+- `pbcopy < /dev/null` : Clear clipboard (prevents accidental paste elsewhere)
+- Key never appears in terminal, history, or remains in clipboard
+
+### Update Existing (Delete + Add)
+```bash
+security delete-generic-password -a "$USER" -s "KEY_NAME" 2>/dev/null; \
+read -s -p "Enter new value: " VALUE && \
+security add-generic-password -a "$USER" -s "KEY_NAME" -w "$VALUE" && \
+unset VALUE
+```
+
+### Batch Check Multiple Keys
+```bash
+for key in OPENAI_API_KEY ANTHROPIC_API_KEY; do
+    if security find-generic-password -a "$USER" -s "$key" -w >/dev/null 2>&1; then
+        echo "[OK] $key"
+    else
+        echo "[MISSING] $key"
+    fi
+done
+```
+</secure_patterns>
+
+<environment_integration>
+## Using with Environment Variables
+
+### Export to Shell
+```bash
+export OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w)
+```
+
+### In .zshrc or .bashrc (loads on shell start)
+```bash
+# ~/.zshrc
+export OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w 2>/dev/null)
+```
+
+### Generate .env File
+```bash
+echo "OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w)" >> .env
+```
+
+### Use in Scripts (Python)
+```python
+import subprocess
+import os
+
+def get_keychain_secret(key_name):
+    result = subprocess.run(
+        ["security", "find-generic-password", "-a", os.environ["USER"], "-s", key_name, "-w"],
+        capture_output=True, text=True
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+```
+
+### Use in Scripts (Node.js)
+```javascript
+const { execSync } = require('child_process');
+
+function getKeychainSecret(keyName) {
+    try {
+        return execSync(`security find-generic-password -a "$USER" -s "${keyName}" -w`)
+            .toString().trim();
+    } catch {
+        return null;
+    }
+}
+```
+</environment_integration>
+
+<troubleshooting>
+## Common Issues
+
+### "security: SecKeychainSearchCopyNext: The specified item could not be found"
+Key doesn't exist. Check the exact name with `security dump-keychain`.
+
+### "already has an entry"
+Key already exists. Delete first, then add:
+```bash
+security delete-generic-password -a "$USER" -s "KEY_NAME"
+security add-generic-password -a "$USER" -s "KEY_NAME" -w "value"
+```
+
+### "User interaction is not allowed"
+Running in a context without Keychain access (e.g., some CI environments). Not applicable for local development.
+
+### Password Prompt on Access
+macOS may prompt for your login password the first time a new application accesses a Keychain item. Click "Always Allow" to prevent future prompts.
+</troubleshooting>

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

@@ -0,0 +1,99 @@
+# Workflow: Add Key to Keychain Securely
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/keychain-commands.md
+</required_reading>
+
+<process>
+## Step 1: Get Key Name
+
+Ask the user what key they want to add. Suggest common options:
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `STRIPE_SECRET_KEY`
+- `DATABASE_URL`
+- Or let them specify a custom name (SCREAMING_SNAKE_CASE)
+
+## Step 2: Check if Key Already Exists and Handle It
+
+Run this check:
+```bash
+security find-generic-password -a "$USER" -s "KEY_NAME" -w >/dev/null 2>&1 && echo "EXISTS" || echo "NEW"
+```
+
+If it exists, ask: "This key already exists. Replace it with a new value?"
+- If yes, delete the old one first: `security delete-generic-password -a "$USER" -s "KEY_NAME" 2>/dev/null`
+- If no, cancel and offer to add a different key
+
+## Step 3: Open Terminal Window for Secure Input
+
+**Claude opens a new Terminal window where the user pastes their key.**
+
+Use this AppleScript command to open Terminal with the secure input prompt:
+
+```bash
+osascript -e 'tell application "Terminal"
+    activate
+    do script "clear && echo \"\" && echo \"====================================\" && echo \"  SECURE API KEY INPUT\" && echo \"====================================\" && echo \"\" && echo \"Paste your key below (it will be invisible)\" && echo \"Then press ENTER\" && echo \"\" && echo -n \"KEY_NAME: \" && read -s K && security add-generic-password -a \"$USER\" -s \"KEY_NAME\" -w \"$K\" && unset K && pbcopy < /dev/null && echo \"\" && echo \"\" && echo \"[SUCCESS] KEY_NAME stored in Keychain\" && echo \"[SUCCESS] Clipboard cleared\" && echo \"\" && echo \"You can close this window now.\" && echo \"\""
+end tell'
+```
+
+**What happens:**
+1. A new Terminal window opens and comes to front
+2. User sees clear instructions
+3. User pastes (Cmd+V) - nothing appears on screen
+4. User presses Enter
+5. Key is stored in Keychain (encrypted)
+6. Clipboard is cleared
+7. Success message shown
+8. User closes the window
+
+**After running:** Wait for user to confirm they completed it, then verify storage.
+
+## Step 4: Verify Storage
+
+Immediately verify the key was stored:
+```bash
+security find-generic-password -a "$USER" -s "KEY_NAME" -w >/dev/null 2>&1 && \
+echo "[VERIFIED] KEY_NAME is now stored in Keychain" || \
+echo "[ERROR] KEY_NAME was not stored - please try again"
+```
+
+## Step 5: Offer Next Steps
+
+Ask the user:
+1. **Add another key** - Repeat this workflow
+2. **Populate .env** - Switch to populate-env.md workflow  
+3. **Done** - Exit skill
+</process>
+
+<terminal_commands>
+## Terminal Window Commands (Claude runs these via osascript)
+
+**Template - replace KEY_NAME:**
+```bash
+osascript -e 'tell application "Terminal"
+    activate
+    do script "clear && echo \"\" && echo \"====================================\" && echo \"  SECURE API KEY INPUT\" && echo \"====================================\" && echo \"\" && echo \"Paste your key below (it will be invisible)\" && echo \"Then press ENTER\" && echo \"\" && echo -n \"KEY_NAME: \" && read -s K && security add-generic-password -a \"$USER\" -s \"KEY_NAME\" -w \"$K\" && unset K && pbcopy < /dev/null && echo \"\" && echo \"\" && echo \"[SUCCESS] KEY_NAME stored in Keychain\" && echo \"[SUCCESS] Clipboard cleared\" && echo \"\" && echo \"You can close this window now.\""
+end tell'
+```
+
+**For updating existing key (delete first):**
+```bash
+osascript -e 'tell application "Terminal"
+    activate
+    do script "clear && echo \"\" && echo \"====================================\" && echo \"  UPDATE API KEY\" && echo \"====================================\" && echo \"\" && security delete-generic-password -a \"$USER\" -s \"KEY_NAME\" 2>/dev/null && echo \"Paste your NEW key below (invisible)\" && echo \"Then press ENTER\" && echo \"\" && echo -n \"KEY_NAME: \" && read -s K && security add-generic-password -a \"$USER\" -s \"KEY_NAME\" -w \"$K\" && unset K && pbcopy < /dev/null && echo \"\" && echo \"\" && echo \"[SUCCESS] KEY_NAME updated in Keychain\" && echo \"[SUCCESS] Clipboard cleared\" && echo \"\" && echo \"You can close this window now.\""
+end tell'
+```
+</terminal_commands>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Key name confirmed with user
+- [ ] Existing key check performed
+- [ ] User provided with secure input command
+- [ ] User confirmed they ran the command
+- [ ] Key storage verified
+- [ ] User offered next steps
+</success_criteria>