1Password Integration for Terraphim AI\n\n## Overview\n\nThis document describes the comprehensive 1Password integration for Terraphim AI, providing enterprise-grade secret management across all components including backend services, desktop applications, and CI/CD pipelines.\n\n## Architecture\n\n### Three-Vault Strategy\n\n- **`Terraphim-Dev`**: Development environment secrets\n- **`Terraphim-Prod`**: Production environment secrets \n- **`Terraphim-Shared`**: Shared secrets across environments (signing keys, monitoring)\n\n### Integration Methods\n\n#### Method 1: Process Memory Injection (Recommended)\n```bash\n# Secrets are injected directly into process memory\nop run --env-file=\".env.terraphim\" -- cargo run\n```\n\n#### Method 2: Secure File Injection\n```bash\n# Secrets are written to secure temporary files\nop inject -i templates/settings.toml.template -o settings.toml\ncargo run\n```\n\n## Setup Instructions\n\n### 1. Install 1Password CLI\n\n**macOS:**\n```bash\nbrew install 1password-cli\n```\n\n**Linux:**\n```bash\ncurl -sS https://downloads.1password.com/linux/keys/1password.asc | gpg --import\nwget https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb\nsudo dpkg -i 1password-cli-amd64-latest.deb\n```\n\n### 2. Initialize 1Password Integration\n\n```bash\n# Run the setup script to create vaults and secret structure\n./scripts/setup-1password-terraphim.sh dev\n\n# For production setup\n./scripts/setup-1password-terraphim.sh prod\n\n# For complete setup\n./scripts/setup-1password-terraphim.sh all\n```\n\n### 3. Populate Secrets\n\nAfter running the setup script, you'll need to update the placeholder values in 1Password with actual secrets:\n\n1. Open 1Password and navigate to the appropriate vault\n2. Update each secret item with real values\n3. Ensure all `op://` references in templates are valid\n\n## Usage\n\n### Backend Services\n\n#### Option 1: Direct 1Password Integration\n```rust\nuse terraphim_settings::DeviceSettings;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n // Load settings with 1Password integration\n let settings = DeviceSettings::load_with_onepassword(None).await?;\n println!(\"Loaded settings with resolved secrets\");\n Ok(())\n}\n```\n\n#### Option 2: Template-based Configuration\n```bash\n# Generate configuration from template\nop inject -i templates/settings.toml.template -o settings.toml\n\n# Run application with resolved configuration\ncargo run\n```\n\n### Desktop Application\n\nThe Tauri desktop application includes built-in 1Password commands:\n\n```typescript\nimport { invoke } from '@tauri-apps/api/tauri';\n\n// Check 1Password status\nconst status = await invoke('onepassword_status');\nconsole.log('1Password available:', status.available);\nconsole.log('1Password authenticated:', status.authenticated);\n\n// Resolve a secret reference\nconst secret = await invoke('onepassword_resolve_secret', {\n request: { reference: 'op://Terraphim-Dev/OpenRouter/API_KEY' }\n});\n\n// Process configuration with 1Password\nconst config = await invoke('onepassword_process_config', {\n request: { config: 'api_key = \"op://Terraphim-Dev/OpenRouter/API_KEY\"' }\n});\n```\n\n### CI/CD Integration\n\nUse the enhanced GitHub Actions workflow with 1Password service accounts:\n\n```yaml\n# .github/workflows/ci-1password.yml\nname: CI with 1Password\n\nenv:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}\n\njobs:\n build:\n steps:\n - name: Install 1Password CLI\n uses: 1password/install-cli-action@v1\n \n - name: Generate configuration\n run: |\n op inject -i templates/env.terraphim.template -o .env.terraphim\n \n - name: Build with secrets\n run: |\n source .env.terraphim\n cargo build --release\n```\n\n## Configuration Templates\n\n### Environment Variables Template\n```bash\n# templates/env.terraphim.template\nOPENROUTER_API_KEY=\"op://Terraphim-Dev/OpenRouter/API_KEY\"\nANTHROPIC_API_KEY=\"op://Terraphim-Dev/Anthropic/API_KEY\"\nATOMIC_SERVER_SECRET=\"op://Terraphim-Dev/AtomicServer/SECRET\"\n```\n\n### Settings Configuration Template\n```toml\n# templates/settings.toml.template\n[profiles.s3]\nbucket = \"op://Terraphim-Dev/AWS_S3/BUCKET_NAME\"\naccess_key_id = \"op://Terraphim-Dev/AWS_S3/ACCESS_KEY_ID\"\nsecret_access_key = \"op://Terraphim-Dev/AWS_S3/SECRET_ACCESS_KEY\"\n```\n\n### Application Configuration Template\n```json\n{\n \"llm\": {\n \"openrouter\": {\n \"api_key\": \"op://Terraphim-Dev/OpenRouter/API_KEY\"\n }\n }\n}\n```\n\n## Secret Categories\n\n### LLM API Keys\n- **OpenRouter**: `API_KEY`, `ORGANIZATION_ID`\n- **Anthropic**: `API_KEY`, `MODEL_NAME`\n- **Ollama**: `BASE_URL`, `MODEL_NAME`\n\n### Search Services\n- **Perplexity**: `API_KEY`\n- **Atomic Server**: `URL`, `SECRET`\n- **ClickUp**: `API_TOKEN`, `TEAM_ID`, `LIST_ID`\n\n### Cloud Storage\n- **AWS S3**: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `BUCKET_NAME`, `REGION`\n- **Cloudflare R2**: `ACCOUNT_ID`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`\n\n### External APIs\n- **GitHub**: `TOKEN`, `ORGANIZATION`, `REPOSITORY`\n- **Discord**: `BOT_TOKEN`, `GUILD_ID`, `CHANNEL_ID`\n\n### Database Connections\n- **PostgreSQL**: `CONNECTION_STRING`, `USERNAME`, `PASSWORD`\n- **Redis**: `URL`, `PASSWORD`, `HOST`, `PORT`\n\n### Shared Secrets\n- **Tauri Signing**: `PRIVATE_KEY`, `PUBLIC_KEY`, `PASSPHRASE`\n- **Code Signing**: `CERTIFICATE_PATH`, `CERTIFICATE_PASSWORD`\n- **Monitoring**: `SENTRY_DSN`, `DATADOG_API_KEY`\n\n## Security Best Practices\n\n### 1. Vault Access Control\n- Use separate vaults for different environments\n- Implement least-privilege access policies\n- Regularly audit vault permissions\n\n### 2. Secret Rotation\n- Rotate API keys regularly\n- Update 1Password references when secrets change\n- Monitor for deprecated or expired secrets\n\n### 3. Template Security\n- Never include hardcoded secrets in templates\n- Use only `op://` references in configuration templates\n- Validate template format before deployment\n\n### 4. CI/CD Security\n- Use 1Password service accounts for automation\n- Limit service account permissions to specific vaults\n- Clean up generated configuration files after use\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1Password CLI Not Authenticated\n```bash\n# Sign in to 1Password\nop signin\n\n# Verify authentication\nop vault list\n```\n\n#### Secret Reference Not Found\n```bash\n# Check vault contents\nop item list --vault=\"Terraphim-Dev\"\n\n# Verify specific item\nop item get \"OpenRouter\" --vault=\"Terraphim-Dev\"\n```\n\n#### Template Processing Failed\n```bash\n# Validate template syntax\nop inject -i templates/env.terraphim.template --dry-run\n\n# Check for malformed references\ngrep -n \"op://\" templates/env.terraphim.template\n```\n\n### Debug Commands\n\n```bash\n# Test 1Password integration\ncargo run --bin debug-onepassword\n\n# Validate configuration templates\n./scripts/validate-templates.sh\n\n# Check secret resolution\nop run --env-file=\".env.terraphim\" -- env | grep -E '^(OPENROUTER|ANTHROPIC)'\n```\n\n## Development Workflow\n\n### Local Development\n1. Install 1Password CLI and authenticate\n2. Run vault setup script: `./scripts/setup-1password-terraphim.sh dev`\n3. Populate development secrets in 1Password\n4. Generate configuration: `op inject -i templates/env.terraphim.template -o .env.terraphim`\n5. Run application: `source .env.terraphim && cargo run`\n\n### Testing\n1. Use separate test vault or test-specific items\n2. Generate test configuration with mock values\n3. Run tests with isolated secrets: `op run --env-file=\".env.test\" -- cargo test`\n\n### Production Deployment\n1. Use production vault and service accounts\n2. Validate all secret references before deployment\n3. Deploy using CI/CD pipeline with 1Password integration\n4. Monitor for secret-related errors and alerts\n\n## Migration Guide\n\n### From Environment Variables\n1. Identify current environment variables\n2. Create corresponding 1Password items\n3. Update configuration templates with `op://` references\n4. Test secret resolution in development\n5. Deploy with 1Password integration\n\n### From Configuration Files\n1. Extract sensitive values from configuration files\n2. Store values in 1Password vaults\n3. Replace sensitive values with `op://` references\n4. Use `op inject` to generate final configuration\n5. Update deployment scripts to use template injection\n\n## Support\n\nFor issues with 1Password integration:\n1. Check this documentation for common solutions\n2. Validate 1Password CLI installation and authentication\n3. Review secret references and vault permissions\n4. Test with minimal configuration first\n5. Contact the Terraphim team for additional support\n\n---\n\n**Next Steps:**\n- Set up your 1Password vaults using the setup script\n- Populate secrets with real values\n- Test integration in development environment\n- Deploy with 1Password-enhanced CI/CD pipeline