docs: Add governance files for OSS release

- Add MIT LICENSE - Add SECURITY.md with responsible disclosure policy * Vulnerability reporting guidelines * YOLO mode security considerations * Agentic AI threat model * Anthropic & OpenAI policy compliance * Security roadmap - Add CONTRIBUTING.md with guidelines * Bug reporting template * Feature request process * PR workflow and commit format * Development setup instructions - Update README.md with policy compliance * Beta software warning * YOLO mode safety notice * Anthropic Acceptable Use Policy * Anthropic Responsible Scaling Policy * Updated security features list - Pin dependencies to specific versions * mcp>=1.0.0,<2.0.0 Ready for public GitHub release.
2025-10-27 00:50:33 +01:00 · 2025-10-27 00:50:33 +01:00 · e5003e9653
commit e5003e9653
parent 4c75bf5713
5 changed files with 365 additions and 10 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,116 @@
+# Contributing to Claude Code Bridge
+
+## Welcome!
+
+Thanks for your interest in contributing! This project aims to make multi-agent
+coordination with Claude Code secure and practical.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Open a GitHub issue with:
+- Description of the bug
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment (OS, Python version, MCP version)
+
+### Suggesting Features
+
+Open a GitHub issue with:
+- Use case description
+- Proposed solution
+- Alternative approaches considered
+- Potential security implications
+
+### Pull Requests
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
+3. **Make your changes**
+4. **Add tests** for new functionality
+5. **Run the test suite**: `python test_bridge.py && python test_security.py`
+6. **Lint your code**: `ruff check . --fix` (if available)
+7. **Commit with descriptive message**: `git commit -m 'feat: Add amazing feature'`
+8. **Push to your fork**: `git push origin feature/amazing-feature`
+9. **Open a Pull Request**
+
+### Commit Message Format
+
+```
+<type>: <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `test`: Test additions/changes
+- `refactor`: Code refactoring
+- `chore`: Maintenance tasks
+- `security`: Security improvements
+
+**Example:**
+```
+feat: Add rate limiting per session
+
+Implement token bucket rate limiter to prevent abuse.
+Configurable limits: 10 req/min, 100 req/hour.
+
+Closes #15
+```
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/claude-code-bridge.git
+cd claude-code-bridge
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run tests
+python test_bridge.py
+python test_security.py
+
+# Run with MCP debug mode
+claude-code --mcp-debug
+```
+
+## Code Style
+
+- Follow PEP 8
+- Use type hints
+- Add docstrings to public methods
+- Keep functions under 50 lines when possible
+- Write self-documenting code
+
+## Testing
+
+- Add tests for all new features
+- Maintain test coverage above 80%
+- Include both positive and negative test cases
+- Test security-critical paths thoroughly
+
+## Security Considerations
+
+When contributing:
+- Never commit secrets or tokens
+- Be extra cautious with YOLO mode changes
+- Consider security implications of all changes
+- Add security tests for authentication/authorization changes
+- Update SECURITY.md if threat model changes
+
+## Questions?
+
+Open a GitHub discussion or issue. We're here to help!
+
+## License
+
+By contributing, you agree that your contributions will be licensed under
+the same MIT License that covers this project.
--- a/21
+++ b/21
@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Danny Stocker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/README.md
+++ b/README.md
@ -2,6 +2,25 @@

 Production-lean MCP server enabling two Claude Code CLI sessions to communicate securely.

+> ⚠️ **Beta Software**: Suitable for development/testing. See [Security Policy](SECURITY.md) before production use.
+
+## ⚠️ YOLO Mode Warning
+
+This project includes an optional YOLO mode for command execution. This is inherently dangerous and should only be used:
+- In isolated development environments
+- With explicit user confirmation
+- By users who understand the risks
+
+See [YOLO_MODE.md](YOLO_MODE.md) and [SECURITY.md](SECURITY.md) for details.
+
+## Policy Compliance
+
+This project complies with:
+- [Anthropic Acceptable Use Policy](https://www.anthropic.com/legal/aup)
+- [Anthropic Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
+
+Users are responsible for ensuring appropriate use and maintaining human oversight of all operations.
+
 ## Security Features ✅

 - **HMAC Authentication**: Session tokens prevent spoofing
@ -11,6 +30,8 @@ Production-lean MCP server enabling two Claude Code CLI sessions to communicate
 - **Token Expiration**: Conversations expire after 3 hours
 - **Schema Validation**: Strict JSON schemas for all tools
 - **No Auto-Execution**: Bridge returns proposals only - no command execution
+- **YOLO Guard**: Multi-stage confirmation for command execution (when enabled)
+- **Rate Limiting**: 10 req/min, 100 req/hour, 500 req/day per session

 ## Installation

--- a/SECURITY.md
+++ b/SECURITY.md
@ -0,0 +1,200 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+**DO NOT** open a public GitHub issue for security vulnerabilities.
+
+Instead, please report security issues responsibly:
+- Create a private security advisory on GitHub
+- Or email: [your-email]@[domain].com (replace with actual email)
+- Subject: "SECURITY: Claude Code Bridge - [brief description]"
+
+Please include:
+1. Description of the vulnerability
+2. Steps to reproduce
+3. Potential impact
+4. Suggested fix (if any)
+
+You will receive a response within 48 hours.
+
+---
+
+## Security Considerations
+
+### ⚠️ YOLO Mode 
+
+YOLO mode enables command execution. This is inherently dangerous and should only be used:
+- In isolated development environments
+- With explicit user confirmation
+- With audit logging enabled
+- By users who understand the risks
+
+**Never enable YOLO mode:**
+- On production systems
+- With untrusted agents
+- On shared machines
+- Without proper backups
+
+**Safety Features:**
+1. Environment variable gate (`YOLO_MODE=1` required)
+2. Double confirmation (typed phrase + one-time code)
+3. Dry-run default (no actual execution without approval token)
+4. Command validation (blocks dangerous patterns)
+5. Audit logging (all actions logged with timestamps)
+6. Timeout limits (commands killed after 30s by default)
+7. Workspace restriction (commands run in specified directory)
+
+### Token Security
+
+Session tokens are cryptographically secure (64-char hex) but:
+- Stored in plain text in SQLite
+- Visible in MCP debug logs
+- Not encrypted at rest
+- Expire after 3 hours
+
+For production use, consider:
+- Encrypting database at rest
+- Using environment-specific key management
+- Shorter token lifetimes for sensitive operations
+
+### Known Limitations
+
+1. **No encryption in transit**: Messages stored as plain text in SQLite
+2. **No user authentication**: Anyone with file access can read database
+3. **Rate limiting**: Implemented but test in your environment
+4. **Command execution risks**: YOLO mode can modify system
+5. **Audit logs not tamper-proof**: SQLite database can be modified
+
+---
+
+## Threat Model
+
+### In Scope:
+- Local multi-agent coordination
+- Development/testing environments
+- Isolated workspaces
+- Human-supervised operations
+
+### Out of Scope:
+- Production deployments without additional safeguards
+- Multi-tenant systems
+- Public-facing APIs
+- Unattended automation
+
+---
+
+## Agentic AI Considerations
+
+### Command Execution Risks
+
+YOLO mode enables agentic behavior (AI taking actions in the real world).
+This carries significant risks:
+
+**Threat Model:**
+- Malicious commands injected by adversarial prompts
+- Unintended destructive operations from AI errors
+- Privilege escalation attempts
+- Data exfiltration
+- Credential theft
+
+**Mitigations:**
+- Command validation (whitelist + blacklist)
+- Execution timeout (30s default)
+- Workspace restriction
+- Audit logging
+- Multi-step approval process
+- Environment-specific gating
+
+**Recommended Controls:**
+- Run in Docker container with no network access
+- Use read-only filesystem where possible
+- Drop all unnecessary capabilities
+- Monitor audit logs continuously
+- Set up alerts for suspicious patterns
+- Maintain offline backups
+
+### Compliance with AI Provider Policies
+
+**Anthropic Claude:**
+- Comply with [Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
+- Maintain human oversight
+- Document intended use
+- Implement operational safeguards
+
+**OpenAI:**
+- Comply with [Usage Policies](https://openai.com/policies/usage-policies)
+- No unauthorized system access
+- No malware development
+- Human-in-the-loop for high-risk actions
+
+**Your Responsibility:**
+- Ensure compliance with provider terms
+- Supervise all agent operations
+- Report security issues responsibly
+- Maintain appropriate logging
+
+### Acceptable Use
+
+**Allowed:**
+- Development and testing workflows
+- Automated code quality checks
+- Safe file operations (within workspace)
+- Git operations (with confirmation)
+- Package management (npm/pip install)
+
+**Not Allowed:**
+- Production deployments without safeguards
+- Unattended operation on critical systems
+- Privilege escalation attempts
+- Network attacks or exploitation
+- Data theft or unauthorized access
+- Malware development or deployment
+
+---
+
+## Security Roadmap
+
+Future security enhancements:
+- [ ] Message encryption at rest
+- [ ] Rate limiting per session (implemented, needs hardening)
+- [ ] Command execution sandboxing (Docker)
+- [ ] Tamper-evident audit logs
+- [ ] TLS for network transport
+- [ ] OAuth/OIDC authentication
+- [ ] Role-based access control
+
+---
+
+## Security Best Practices
+
+When using this bridge:
+
+1. **Isolate**: Run in dedicated VM or container
+2. **Monitor**: Review audit logs regularly
+3. **Limit**: Use restrictive YOLO modes
+4. **Backup**: Maintain offline backups
+5. **Update**: Keep dependencies current
+6. **Test**: Validate before production use
+7. **Document**: Record configuration decisions
+
+---
+
+## Contact
+
+For security concerns:
+- GitHub Security Advisories (preferred)
+- Email: [Add your email here]
+
+For general questions:
+- GitHub Issues
+- GitHub Discussions
+
+---
+
+**Last Updated:** 2025-10-27
--- a/requirements.txt
+++ b/requirements.txt
@ -1,9 +1,10 @@
-# Claude Code Multi-Agent Bridge Requirements
+# Claude Code Bridge Requirements
+# Production dependencies

-# Core MCP SDK for Model Context Protocol
-mcp>=1.0.0
+# MCP Server (pinned to specific version for stability)
+mcp>=1.0.0,<2.0.0

-# Standard library dependencies (included with Python)
+# Python standard library (no installation needed):
 # - asyncio
 # - json
 # - hmac
@ -14,9 +15,5 @@ mcp>=1.0.0
 # - subprocess
 # - datetime
 # - pathlib
-
-# Optional: For enhanced features
-# redis>=4.0.0  # If using Redis instead of SQLite
-
-# Installation:
-# pip install -r requirements.txt
+# - typing
+# - collections