Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

docs/development/SECURITY.md

@@ -0,0 +1,256 @@
+# Security Best Practices for Ruvector Development
+
+## Environment Variables and Secrets
+
+### Never Commit Secrets
+
+**Critical**: Never commit API keys, tokens, or credentials to version control.
+
+### Protected Files
+
+The following files are in `.gitignore` and should **NEVER** be committed:
+
+```
+.env                    # Main environment configuration
+.env.local             # Local overrides
+.env.*.local           # Environment-specific local configs
+*.key                  # Private keys
+*.pem                  # Certificates
+credentials.json       # Credential files
+```
+
+### Using .env Files
+
+1. **Copy the template**:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Add your credentials**:
+   ```bash
+   # Edit .env with your actual values
+   nano .env
+   ```
+
+3. **Verify .env is ignored**:
+   ```bash
+   git status --ignored | grep .env
+   # Should show: .env (in gitignore)
+   ```
+
+## API Keys Management
+
+### Crates.io API Key
+
+**Required for publishing crates to crates.io**
+
+1. **Generate Token**:
+   - Visit [crates.io/me](https://crates.io/me)
+   - Click "New Token"
+   - Name: "Ruvector Publishing"
+   - Permissions: "publish-new" and "publish-update"
+   - Copy the token immediately (shown only once)
+
+2. **Store Securely**:
+   ```bash
+   # Add to .env (which is gitignored)
+   echo "CRATES_API_KEY=your-actual-token-here" >> .env
+   ```
+
+3. **Use from .env**:
+   ```bash
+   # Publishing script automatically loads from .env
+   ./scripts/publish-crates.sh
+   ```
+
+### Key Rotation
+
+Rotate API keys regularly:
+
+```bash
+# 1. Generate new token on crates.io
+# 2. Update .env with new token
+# 3. Test with: cargo login $CRATES_API_KEY
+# 4. Revoke old token on crates.io
+```
+
+## Development Secrets
+
+### What NOT to Commit
+
+❌ **Never commit**:
+- API keys (crates.io, npm, etc.)
+- Database credentials
+- Private keys (.key, .pem files)
+- OAuth tokens
+- Session secrets
+- Encryption keys
+- Service account credentials
+
+✅ **Safe to commit**:
+- `.env.example` (template with no real values)
+- Public configuration
+- Example data (non-sensitive)
+- Documentation
+
+### Pre-commit Checks
+
+Before committing, verify no secrets are staged:
+
+```bash
+# Check staged files
+git diff --staged
+
+# Search for potential secrets
+git diff --staged | grep -i "api_key\|secret\|password\|token"
+
+# Use git-secrets (optional)
+git secrets --scan
+```
+
+### GitHub Secret Scanning
+
+GitHub automatically scans for common secrets. If detected:
+
+1. **Immediately revoke** the exposed credential
+2. **Generate a new** credential
+3. **Update .env** with new credential
+4. **Force push** to remove from history (if needed):
+   ```bash
+   # Dangerous! Only if absolutely necessary
+   git filter-branch --force --index-filter \
+     "git rm --cached --ignore-unmatch .env" \
+     --prune-empty --tag-name-filter cat -- --all
+   ```
+
+## CI/CD Secrets
+
+### GitHub Actions
+
+Store secrets in GitHub repository settings:
+
+1. Go to repository Settings → Secrets and variables → Actions
+2. Add secrets:
+   - `CRATES_API_KEY` - for publishing
+   - `CODECOV_TOKEN` - for code coverage (optional)
+
+3. Use in workflows:
+   ```yaml
+   - name: Publish to crates.io
+     env:
+       CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_API_KEY }}
+     run: cargo publish
+   ```
+
+### Local Development
+
+For local development, use `.env`:
+
+```bash
+# .env (gitignored)
+CRATES_API_KEY=cio-xxx...
+RUST_LOG=debug
+```
+
+Load in scripts:
+```bash
+# Load from .env
+export $(grep -v '^#' .env | xargs)
+```
+
+## Code Signing
+
+### Signing Releases
+
+For production releases:
+
+```bash
+# Generate GPG key (if not exists)
+gpg --gen-key
+
+# Sign git tags
+git tag -s v0.1.0 -m "Release v0.1.0"
+
+# Verify signature
+git tag -v v0.1.0
+```
+
+### Cargo Package Signing
+
+Cargo doesn't support package signing yet, but you can:
+
+1. Sign the git tag
+2. Include checksums in release notes
+3. Provide GPG signatures for binary releases
+
+## Dependency Security
+
+### Audit Dependencies
+
+Regularly audit dependencies for vulnerabilities:
+
+```bash
+# Install cargo-audit
+cargo install cargo-audit
+
+# Run security audit
+cargo audit
+
+# Fix vulnerabilities
+cargo audit fix
+```
+
+### Automated Scanning
+
+Enable GitHub Dependabot:
+
+1. Go to repository Settings → Security → Dependabot
+2. Enable "Dependabot alerts"
+3. Enable "Dependabot security updates"
+
+## Reporting Security Issues
+
+### Responsible Disclosure
+
+If you discover a security vulnerability:
+
+1. **Do NOT** open a public GitHub issue
+2. **Email**: [security@ruv.io](mailto:security@ruv.io)
+3. **Include**:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+### Response Timeline
+
+- **24 hours**: Initial response
+- **7 days**: Status update
+- **30 days**: Fix released (if confirmed)
+
+## Security Checklist
+
+Before releasing:
+
+- [ ] No secrets in code or config files
+- [ ] `.env` is in `.gitignore`
+- [ ] `.env.example` has no real values
+- [ ] All dependencies audited (`cargo audit`)
+- [ ] Git tags are signed
+- [ ] API keys rotated if exposed
+- [ ] Security scan passed (GitHub)
+- [ ] Documentation reviewed for sensitive info
+
+## Resources
+
+- [Cargo Security Guidelines](https://doc.rust-lang.org/cargo/reference/security.html)
+- [GitHub Secret Scanning](https://docs.github.com/en/code-security/secret-scanning)
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [Rust Security Guidelines](https://anssi-fr.github.io/rust-guide/)
+
+## Support
+
+For security questions:
+- Email: [security@ruv.io](mailto:security@ruv.io)
+- Documentation: [docs.ruv.io](https://docs.ruv.io)
+- Community: [Discord](https://discord.gg/ruvnet)