@northbridge-security/secureai 0.1.13

package/docs/guides/agents.onepassword.md

@@ -0,0 +1,285 @@
+# 1Password Integration Guide for AI Agents
+
+This guide provides AI agents with essential information for secure credential management using 1Password. All AI development tools in this ecosystem use 1Password via MCP servers, ensuring credentials are never exposed to AI agents directly.
+
+## Target Audience
+
+This guide is for AI agents operating within:
+
+- **Claude Code** - Anthropic's CLI assistant
+- **Cursor IDE** - AI-first code editor
+- **Codex CLI** - OpenAI command-line interface
+
+Users of the ai-toolkit should have 1Password configured for secure credential management.
+
+## Security Model
+
+### Why 1Password + MCP
+
+**Problem**: AI agents need access to external services (APIs, databases) but should never see actual credentials.
+
+**Solution**: MCP servers handle credential injection at runtime:
+
+1. Configuration files contain `op://` references (not actual secrets)
+2. 1Password CLI resolves references when MCP servers start
+3. AI agents interact via MCP tools - never see the actual API keys
+4. Biometric authentication required for credential access
+
+### Credential Protection
+
+**AI agents are blocked from:**
+
+- Reading MCP configuration files containing credentials
+- Executing commands that would expose credentials
+- Accessing `~/.claude/.credentials.json` or similar files
+
+**This protection is enforced via `~/.claude/settings.json` deny rules.**
+
+## Installation & Setup
+
+### Prerequisites
+
+1. **1Password Desktop App** (version 8.0+)
+   - Download from: https://1password.com/downloads
+   - Sign in to your 1Password account
+   - Enable biometric unlock (Touch ID / Windows Hello)
+
+2. **1Password CLI**
+   - macOS: `brew install 1password-cli`
+   - Linux: See https://developer.1password.com/docs/cli/get-started
+   - Windows: `winget install AgileBits.1PasswordCLI`
+
+3. **Enable CLI Integration**
+   - 1Password → Settings → Developer
+   - Enable "Integrate with 1Password CLI"
+   - Enable "Connect with 1Password CLI"
+
+### Configure MCP Servers with 1Password
+
+**Use ai-toolkit installer** (recommended):
+
+```bash
+ai-toolkit install -t claude
+```
+
+This command:
+
+- Configures Task Master MCP with `op://` references
+- Configures GitHub MCP with `op://` references
+- Sets up credential protection in `~/.claude/settings.json`
+- Installs security hooks to prevent credential exposure
+
+**What gets configured** (`~/.claude/` managed by Claude MCP):
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "npx",
+      "args": ["-y", "task-master-ai"],
+      "env": {
+        "ANTHROPIC_API_KEY": "op://Private/Anthropic/API Key",
+        "PERPLEXITY_API_KEY": "op://Private/Perplexity/API Key"
+      }
+    },
+    "github-mcp": {
+      "command": "npx",
+      "args": ["-y", "@github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "op://Private/GitHub/API Token (Read-Only)/token"
+      }
+    }
+  }
+}
+```
+
+### Store Credentials in 1Password
+
+**Required items in 1Password:**
+
+| Item Name  | Vault   | Field                       | Purpose                          |
+| ---------- | ------- | --------------------------- | -------------------------------- |
+| Anthropic  | Private | API Key                     | Claude models for Task Master    |
+| Perplexity | Private | API Key                     | Research features in Task Master |
+| GitHub     | Private | API Token (Read-Only)/token | GitHub MCP access                |
+
+**Creating items in 1Password:**
+
+1. Open 1Password
+2. Click "+" → API Credential
+3. Set Title: `Anthropic` (or service name)
+4. Set Vault: `Private`
+5. Add field: `API Key` with your actual key value
+6. Save
+
+**op:// reference format:**
+
+```text
+op://[vault]/[item]/[field]
+
+Examples:
+op://Private/Anthropic/API Key
+op://Private/GitHub/API Token (Read-Only)/token
+op://Development/PostgreSQL/connection_string
+```
+
+## For AI Agents
+
+### What You CAN Do
+
+- Use MCP tools normally (credentials handled automatically)
+- Call `mcp__task_master_ai__*` tools
+- Call `mcp__github_mcp__*` tools
+- Request installation via `ai-toolkit install`
+
+### What You CANNOT Do
+
+- Read MCP configuration files
+- Execute `claude mcp get` (exposes credentials)
+- Read `~/.claude/.credentials.json`
+- Access environment files with credentials
+- Use CLI commands that require manual credential setup
+
+### When MCP is Not Available
+
+**Do NOT fall back to CLI with manual credentials.**
+
+Instead, guide the user to configure MCP properly:
+
+```text
+The Task Master MCP server is not available.
+
+To configure it:
+1. Run: ai-toolkit install -t claude
+2. Ensure 1Password is unlocked
+3. Restart Claude Code
+
+This will securely configure Task Master with your API keys from 1Password.
+```
+
+### Checking MCP Status
+
+```javascript
+// Check if MCP server is available
+// This is safe - doesn't expose credentials
+const servers = await bash("claude mcp list");
+
+// Check for specific server
+if (servers.stdout.includes("task-master-ai")) {
+  // MCP is available, use it
+  await mcp__task_master_ai__next_task({ projectRoot: "/path/to/project" });
+} else {
+  // Guide user to install
+  console.log("Task Master MCP not configured. Run: ai-toolkit install -t claude");
+}
+```
+
+## Troubleshooting
+
+### MCP Server Won't Start
+
+**Symptom**: `claude mcp list` shows server but tools fail
+
+**Cause**: 1Password not unlocked or credentials not found
+
+**Solution**:
+
+1. Ensure 1Password desktop app is open
+2. Unlock 1Password (biometric or password)
+3. Verify items exist: `op item get "Anthropic" --vault "Private"`
+4. Restart Claude Code
+
+### Credential Reference Not Found
+
+**Symptom**: MCP server fails with "item not found"
+
+**Cause**: op:// reference doesn't match 1Password item
+
+**Solution**:
+
+1. Check exact item name in 1Password
+2. Check exact field name (case-sensitive)
+3. Check vault name
+4. Update MCP configuration via `ai-toolkit install`
+
+### Permission Denied
+
+**Symptom**: "Permission denied" when accessing 1Password
+
+**Cause**: CLI not integrated with desktop app
+
+**Solution**:
+
+1. Open 1Password → Settings → Developer
+2. Enable "Integrate with 1Password CLI"
+3. Try again
+
+### Biometric Unlock Fails
+
+**Symptom**: Touch ID / Windows Hello not working
+
+**Solution**:
+
+1. Lock and unlock 1Password manually
+2. Re-enable biometric: Settings → Security → Unlock
+3. Sign out and sign back in to CLI: `op signout && op signin`
+
+## Security Best Practices
+
+### DO
+
+- Use `ai-toolkit install` for configuration
+- Keep 1Password desktop app running
+- Use biometric unlock for convenience and security
+- Use separate vaults for different environments (Dev/Prod)
+- Rotate API keys periodically (1Password handles reference updates)
+
+### DON'T
+
+- Manually edit MCP configuration with raw credentials
+- Copy API keys to clipboard for pasting
+- Store credentials in `.env` files (use `op://` references)
+- Share master password via insecure channels
+- Commit any file containing actual credentials
+
+## op:// Reference Format
+
+### Syntax
+
+```text
+op://[vault-name/]item-name[/section-name]/field-name
+```
+
+### Components
+
+- **vault-name** (optional): Vault containing the item. Defaults to "Private" if omitted.
+- **item-name** (required): Name or UUID of the 1Password item
+- **section-name** (optional): Section within the item
+- **field-name** (required): Field name to retrieve
+
+### Examples
+
+```bash
+# Basic (default vault)
+op://database/password
+
+# With vault
+op://Private/API Keys/token
+
+# With section
+op://Production/AWS/Access Keys/access_key_id
+
+# Spaces in names (URL-encoded)
+op://Private/My%20API%20Keys/my%20token
+```
+
+## External Resources
+
+- **1Password CLI Reference**: https://developer.1password.com/docs/cli/
+- **Secret References Guide**: https://developer.1password.com/docs/cli/secrets-reference-syntax
+- **SSH Agent Setup**: https://developer.1password.com/docs/ssh/
+- **AI Toolkit Documentation**: See `docs/1password.md` for complete integration guide
+
+---
+
+**For AI Agents**: Never attempt to read or expose credentials. Always use MCP tools which handle credential injection securely. If MCP is not configured, guide users to run `ai-toolkit install`.