aidevops 2.52.1

package/.agent/tools/credentials/environment-variables.md

@@ -0,0 +1,180 @@
+---
+description: Environment variables integration for credentials
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Environment Variables Integration
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Priority**: Environment variables > .env files > config files > defaults
+- **OpenAI**: `OPENAI_API_KEY` (sk-...), `OPENAI_BASE_URL`
+- **Anthropic**: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`
+- **Others**: `AI_GATEWAY_API_KEY`, `GOOGLE_API_KEY`, `AZURE_OPENAI_API_KEY`
+- **DSPy test**: `./.agent/scripts/dspy-helper.sh test`
+- **Check keys**: `env | grep -E "(OPENAI|ANTHROPIC|CLAUDE)_API_KEY"`
+- **Test OpenAI**: `curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models | head -20`
+- **Benefits**: Secure (no keys in files), convenient (works immediately), flexible (override per-project)
+<!-- AI-CONTEXT-END -->
+
+## Automatic API Key Detection
+
+Both DSPy and DSPyGround are configured to **automatically use your terminal session's API keys**. No additional configuration needed!
+
+### **Current Environment**
+
+Your terminal session has these API keys available:
+
+- ✅ `OPENAI_API_KEY` - Detected and ready to use
+
+### **How It Works**
+
+#### **DSPy Integration**
+
+DSPy uses this priority order:
+
+1. **Environment variables** (your terminal session) - **HIGHEST PRIORITY**
+2. Configuration file values - fallback only
+
+```python
+# DSPy automatically checks environment first
+api_key = os.getenv("OPENAI_API_KEY", config_fallback)
+lm = dspy.LM(model="openai/gpt-3.5-turbo", api_key=api_key)
+```
+
+#### **DSPyGround Integration**
+
+DSPyGround uses `.env` files that reference your environment:
+
+```bash
+# .env file automatically uses your terminal session variables
+OPENAI_API_KEY=${OPENAI_API_KEY}  # References your existing key
+```
+
+## 🚀 **Quick Test**
+
+### **Test DSPy with Your API Key**
+
+```bash
+cd data/dspy/test-project
+source ../../../python-env/dspy-env/bin/activate
+python3 main.py
+```
+
+### **Test DSPyGround with Your API Key**
+
+```bash
+cd data/dspyground/test-agent
+# Your OPENAI_API_KEY is automatically available
+node -e "console.log('API Key:', process.env.OPENAI_API_KEY?.slice(0,10) + '...')"
+```
+
+## 🔧 **Supported Environment Variables**
+
+### **OpenAI**
+
+- `OPENAI_API_KEY` - ✅ **Currently set in your environment**
+- `OPENAI_BASE_URL` - Custom endpoint (optional)
+
+### **Anthropic**
+
+- `ANTHROPIC_API_KEY` - For Claude models
+- `ANTHROPIC_BASE_URL` - Custom endpoint (optional)
+
+### **Other Providers**
+
+- `AI_GATEWAY_API_KEY` - For DSPyGround AI Gateway
+- `GOOGLE_API_KEY` - For Gemini models
+- `AZURE_OPENAI_API_KEY` - For Azure OpenAI
+
+## 📋 **Configuration Priority**
+
+Both tools follow this priority order:
+
+1. **Environment Variables** (your terminal session)
+2. `.env` files (project-specific)
+3. Configuration files (fallback)
+4. Default values (last resort)
+
+## ✨ **Benefits**
+
+### **Security**
+
+- API keys stay in your secure environment
+- No need to store keys in config files
+- Consistent across all projects
+
+### **Convenience**
+
+- Works immediately with your existing setup
+- No additional configuration required
+- Same keys work for all AI tools
+
+### **Flexibility**
+
+- Override per-project with `.env` files
+- Fallback to config files if needed
+- Easy switching between different keys
+
+## 🎯 **Quick Start Commands**
+
+Since your `OPENAI_API_KEY` is already set, you can immediately:
+
+```bash
+# Test DSPy
+./.agent/scripts/dspy-helper.sh test
+
+# Create and run DSPy project
+./.agent/scripts/dspy-helper.sh init my-bot
+cd data/dspy/my-bot
+source ../../../python-env/dspy-env/bin/activate
+python3 main.py
+
+# Create DSPyGround project
+./.agent/scripts/dspyground-helper.sh init my-agent
+cd data/dspyground/my-agent
+# Add AI_GATEWAY_API_KEY to .env if using AI Gateway
+# Otherwise, your OPENAI_API_KEY works directly
+```
+
+## 🔍 **Troubleshooting**
+
+### **Check Your Environment**
+
+```bash
+# Verify API keys are set
+env | grep -E "(OPENAI|ANTHROPIC|CLAUDE)_API_KEY"
+
+# Test API key format
+echo $OPENAI_API_KEY | grep -E "^sk-"
+```
+
+### **Test API Connectivity**
+
+```bash
+# Test OpenAI API
+curl -H "Authorization: Bearer $OPENAI_API_KEY" \
+     https://api.openai.com/v1/models | head -20
+```
+
+### **Common Issues**
+
+1. **API Key Not Found**: Check `echo $OPENAI_API_KEY`
+2. **Wrong Format**: OpenAI keys start with `sk-`
+3. **Permissions**: Ensure key has required permissions
+4. **Rate Limits**: Check API usage limits
+
+## 🎉 **Ready to Use!**
+
+Your environment is already configured! Both DSPy and DSPyGround will automatically use your existing `OPENAI_API_KEY` without any additional setup.

package/.agent/tools/credentials/vaultwarden.md

@@ -0,0 +1,382 @@
+---
+description: Vaultwarden self-hosted password management
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# Vaultwarden (Self-hosted Bitwarden) Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Type**: Self-hosted password manager (Bitwarden API compatible)
+- **CLI**: `npm install -g @bitwarden/cli` then `bw`
+- **Auth**: `bw login email` then `export BW_SESSION=$(bw unlock --raw)`
+- **Config**: `configs/vaultwarden-config.json`
+- **Commands**: `vaultwarden-helper.sh [instances|status|login|unlock|list|search|get|get-password|create|audit|start-mcp] [instance] [args]`
+- **Session**: `BW_SESSION` env var required after unlock
+- **Lock**: `bw lock` and `unset BW_SESSION` when done
+- **MCP**: Port 3002 for AI assistant credential access
+- **Backup**: `bw export --format json` (encrypt with GPG)
+<!-- AI-CONTEXT-END -->
+
+Vaultwarden is a self-hosted, lightweight implementation of the Bitwarden server API, providing secure password and secrets management with full API access and MCP integration.
+
+## Provider Overview
+
+### **Vaultwarden Characteristics:**
+
+- **Service Type**: Self-hosted password and secrets management
+- **Compatibility**: Full Bitwarden API compatibility
+- **Architecture**: Lightweight Rust implementation
+- **Security**: End-to-end encryption with zero-knowledge architecture
+- **API Support**: Complete REST API for automation
+- **MCP Integration**: Real-time vault access for AI assistants
+- **Multi-platform**: Web, desktop, mobile, and CLI access
+
+### **Best Use Cases:**
+
+- **DevOps credential management** with secure API access
+- **Team password sharing** with organization support
+- **Development secrets** management and rotation
+- **Infrastructure credentials** with automated access
+- **Secure note storage** for configuration and documentation
+- **API key management** with audit trails and access control
+
+## 🔧 **Configuration**
+
+### **Setup Configuration:**
+
+```bash
+# Copy template
+cp configs/vaultwarden-config.json.txt configs/vaultwarden-config.json
+
+# Edit with your Vaultwarden instance details
+```
+
+### **Multi-Instance Configuration:**
+
+```json
+{
+  "instances": {
+    "production": {
+      "server_url": "https://vault.yourdomain.com",
+      "description": "Production Vaultwarden instance",
+      "users_count": 25,
+      "organizations": [
+        {
+          "name": "Company Organization",
+          "id": "org-uuid-here"
+        }
+      ]
+    },
+    "development": {
+      "server_url": "https://dev-vault.yourdomain.com",
+      "description": "Development Vaultwarden instance",
+      "users_count": 10
+    }
+  }
+}
+```
+
+### **Bitwarden CLI Setup:**
+
+```bash
+# Install Bitwarden CLI
+npm install -g @bitwarden/cli
+
+# Or download binary from:
+# https://bitwarden.com/download/
+
+# Verify installation
+bw --version
+```
+
+## 🚀 **Usage Examples**
+
+### **Basic Commands:**
+
+```bash
+# List all Vaultwarden instances
+./.agent/scripts/vaultwarden-helper.sh instances
+
+# Get vault status
+./.agent/scripts/vaultwarden-helper.sh status production
+
+# Login to vault
+./.agent/scripts/vaultwarden-helper.sh login production user@example.com
+
+# Unlock vault (after login)
+./.agent/scripts/vaultwarden-helper.sh unlock
+```
+
+### **Vault Management:**
+
+```bash
+# List all vault items
+./.agent/scripts/vaultwarden-helper.sh list production
+
+# Search vault items
+./.agent/scripts/vaultwarden-helper.sh search production "github"
+
+# Get specific item
+./.agent/scripts/vaultwarden-helper.sh get production item-uuid
+
+# Get password for item
+./.agent/scripts/vaultwarden-helper.sh get-password production "GitHub Account"
+
+# Get username for item
+./.agent/scripts/vaultwarden-helper.sh get-username production "GitHub Account"
+```
+
+### **Item Management:**
+
+```bash
+# Create new vault item
+./.agent/scripts/vaultwarden-helper.sh create production "New Service" username password123 https://service.com
+
+# Update vault item
+./.agent/scripts/vaultwarden-helper.sh update production item-uuid password newpassword123
+
+# Delete vault item
+./.agent/scripts/vaultwarden-helper.sh delete production item-uuid
+
+# Generate secure password
+./.agent/scripts/vaultwarden-helper.sh generate 20 true
+```
+
+### **Organization Management:**
+
+```bash
+# List organization vault items
+./.agent/scripts/vaultwarden-helper.sh org-list production org-uuid
+
+# Sync vault with server
+./.agent/scripts/vaultwarden-helper.sh sync production
+
+# Export vault (encrypted)
+./.agent/scripts/vaultwarden-helper.sh export production json vault-backup.json
+```
+
+### **Security & Auditing:**
+
+```bash
+# Audit vault security
+./.agent/scripts/vaultwarden-helper.sh audit production
+
+# Lock vault
+./.agent/scripts/vaultwarden-helper.sh lock
+
+# Start MCP server for AI access
+./.agent/scripts/vaultwarden-helper.sh start-mcp production 3002
+
+# Test MCP connection
+./.agent/scripts/vaultwarden-helper.sh test-mcp 3002
+```
+
+## 🛡️ **Security Best Practices**
+
+### **Instance Security:**
+
+- **HTTPS only**: Always use HTTPS for Vaultwarden instances
+- **Strong master passwords**: Enforce strong master password policies
+- **Two-factor authentication**: Enable 2FA for all users
+- **Regular backups**: Maintain encrypted backups of vault data
+- **Access monitoring**: Monitor and audit vault access
+
+### **API Security:**
+
+```bash
+# Use secure session management
+export BW_SESSION=$(bw unlock --raw)
+
+# Clear session when done
+unset BW_SESSION
+bw lock
+
+# Regular security audits
+./.agent/scripts/vaultwarden-helper.sh audit production
+```
+
+### **Organizational Security:**
+
+- **Role-based access**: Implement proper role-based access control
+- **Shared vault policies**: Define clear policies for shared vaults
+- **Regular audits**: Perform regular security audits
+- **Access reviews**: Review user access regularly
+- **Incident response**: Have incident response procedures
+
+## 🔍 **Troubleshooting**
+
+### **Common Issues:**
+
+#### **Connection Issues:**
+
+```bash
+# Test server connectivity
+curl -I https://vault.yourdomain.com
+
+# Check Bitwarden CLI configuration
+bw config
+
+# Verify server URL
+bw config server https://vault.yourdomain.com
+```
+
+#### **Authentication Issues:**
+
+```bash
+# Check login status
+bw status
+
+# Re-login if needed
+bw logout
+bw login user@example.com
+
+# Unlock vault
+bw unlock
+```
+
+#### **Sync Issues:**
+
+```bash
+# Force sync with server
+bw sync --force
+
+# Check sync status
+bw status
+
+# Clear local cache if needed
+bw logout
+bw login user@example.com
+```
+
+## 📊 **MCP Integration**
+
+### **Bitwarden MCP Server:**
+
+```bash
+# Start Bitwarden MCP server
+./.agent/scripts/vaultwarden-helper.sh start-mcp production 3002
+
+# Test MCP server
+./.agent/scripts/vaultwarden-helper.sh test-mcp 3002
+
+# Configure in AI assistant
+# Add to MCP servers configuration:
+{
+  "bitwarden": {
+    "command": "bitwarden-mcp-server",
+    "args": ["--port", "3002"],
+    "env": {
+      "BW_SERVER": "https://vault.yourdomain.com"
+    }
+  }
+}
+```
+
+### **AI Assistant Integration:**
+
+The MCP server enables AI assistants to:
+
+- **Retrieve credentials** securely for automation tasks
+- **Generate secure passwords** with custom policies
+- **Audit vault security** and identify weak passwords
+- **Manage vault items** with proper authentication
+- **Access shared organization** vaults for team credentials
+
+## 🔄 **Backup & Recovery**
+
+### **Vault Backup:**
+
+```bash
+# Export encrypted vault
+./.agent/scripts/vaultwarden-helper.sh export production json vault-backup-$(date +%Y%m%d).json
+
+# Secure backup file
+chmod 600 vault-backup-*.json
+
+# Store backup securely (encrypted storage recommended)
+```
+
+### **Automated Backup:**
+
+```bash
+#!/bin/bash
+# Automated vault backup script
+INSTANCE="production"
+BACKUP_DIR="/secure/backups/vaultwarden"
+DATE=$(date +%Y%m%d-%H%M%S)
+
+# Create backup
+./.agent/scripts/vaultwarden-helper.sh export $INSTANCE json "$BACKUP_DIR/vault-$DATE.json"
+
+# Encrypt backup
+gpg --cipher-algo AES256 --compress-algo 1 --s2k-mode 3 \
+    --s2k-digest-algo SHA512 --s2k-count 65536 --symmetric \
+    "$BACKUP_DIR/vault-$DATE.json"
+
+# Remove unencrypted backup
+rm "$BACKUP_DIR/vault-$DATE.json"
+
+# Cleanup old backups (keep 30 days)
+find "$BACKUP_DIR" -name "vault-*.json.gpg" -mtime +30 -delete
+```
+
+## 📚 **Best Practices**
+
+### **Vault Organization:**
+
+1. **Logical categorization**: Organize items by service, environment, or team
+2. **Consistent naming**: Use consistent naming conventions
+3. **Regular cleanup**: Remove unused or outdated credentials
+4. **Documentation**: Document credential purposes and rotation schedules
+5. **Access control**: Implement proper access controls for shared items
+
+### **Password Management:**
+
+- **Strong passwords**: Use generated passwords with high entropy
+- **Regular rotation**: Rotate passwords regularly, especially for critical services
+- **Unique passwords**: Never reuse passwords across services
+- **Secure sharing**: Use organization vaults for team credential sharing
+- **Audit regularly**: Regular security audits to identify weak passwords
+
+### **Automation Integration:**
+
+- **API access**: Use API access for automated credential retrieval
+- **Session management**: Properly manage CLI sessions and tokens
+- **Error handling**: Implement proper error handling for automation
+- **Logging**: Log credential access for audit purposes
+- **Rate limiting**: Respect API rate limits in automation
+
+## 🎯 **AI Assistant Integration**
+
+### **Automated Credential Management:**
+
+- **Secure retrieval**: AI can securely retrieve credentials for automation
+- **Password generation**: AI can generate secure passwords with policies
+- **Vault auditing**: AI can audit vault security and identify issues
+- **Credential rotation**: AI can assist with credential rotation workflows
+- **Access monitoring**: AI can monitor and report on credential access
+
+### **DevOps Workflows:**
+
+- **Infrastructure deployment**: Secure credential access for deployments
+- **CI/CD integration**: Secure credential injection into pipelines
+- **Service configuration**: Automated service configuration with credentials
+- **Monitoring integration**: Secure access to monitoring service credentials
+- **Incident response**: Quick access to emergency credentials
+
+  task: true
+---
+
+**Vaultwarden provides enterprise-grade password and secrets management with comprehensive API access, making it ideal for secure DevOps workflows and AI-assisted credential management.** 🚀