diff --git a/CLAUDE.md b/CLAUDE.md index ab12cf4..141b16c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -91,25 +91,22 @@ Use the demo repository for testing auto-tagging and webhook functionality: ### Claude Authentication Options -This service supports three authentication methods for different use cases: +This service supports three authentication methods: -| Method | Best For | Cost | Documentation | -|--------|----------|------|---------------| -| **Setup Container** | Development/Personal (subscription users) | Fixed subscription cost | [Setup Container Guide](./docs/setup-container-guide.md) | -| **ANTHROPIC_API_KEY** | Production/Team | Pay-per-use (high cost) | [Authentication Guide](./docs/claude-authentication-guide.md) | -| **AWS Bedrock** | Enterprise | Enterprise pricing | [Authentication Guide](./docs/claude-authentication-guide.md) | +- **Setup Container**: Personal subscription authentication - [Setup Container Guide](./docs/setup-container-guide.md) +- **ANTHROPIC_API_KEY**: Direct API key authentication - [Authentication Guide](./docs/claude-authentication-guide.md) +- **AWS Bedrock**: Enterprise AWS integration - [Authentication Guide](./docs/claude-authentication-guide.md) -#### Quick Start: Setup Container (Personal/Development) -For Claude Max subscribers (5x or 20x plans) wanting to use their subscription for automation: +#### Quick Start: Setup Container +For personal subscription users: ```bash # 1. Run interactive authentication setup ./scripts/setup/setup-claude-interactive.sh # 2. In container: authenticate with your subscription -claude login # Follow browser flow -claude status # Verify -exit # Save authentication +claude --dangerously-skip-permissions # Follow authentication flow +exit # Save authentication # 3. Test captured authentication ./scripts/setup/test-claude-auth.sh diff --git a/docs/claude-authentication-guide.md b/docs/claude-authentication-guide.md index f871b9b..dfb3a1d 100644 --- a/docs/claude-authentication-guide.md +++ b/docs/claude-authentication-guide.md @@ -1,31 +1,20 @@ # Claude Authentication Guide -This guide covers three authentication methods for using Claude with the webhook service, each designed for different use cases and requirements. +This guide covers three authentication methods for using Claude with the webhook service. ## Authentication Methods Overview -| Method | Best For | Cost | Stability | Setup Complexity | -|--------|----------|------|-----------|------------------| -| **Setup Container** | Development/Personal | Fixed subscription | Good | Medium | -| **ANTHROPIC_API_KEY** | Production/Team | High usage costs | Excellent | Low | -| **AWS Bedrock** | Enterprise | Moderate | Excellent | High | +| Method | Use Case | Setup Complexity | +|--------|----------|------------------| +| **Setup Container** | Personal development | Medium | +| **ANTHROPIC_API_KEY** | Production environments | Low | +| **AWS Bedrock** | Enterprise integration | High | --- -## ๐Ÿณ Option 1: Setup Container (Development/Personal) +## ๐Ÿณ Option 1: Setup Container (Personal Development) -**Best for:** Developers with Claude Max subscriptions (10x or 20x plans) who want to use their existing subscription for automation. Note: Claude Code is not included with Claude Pro plans. - -### Advantages -- โœ… **Cost-effective**: Use your existing Claude subscription -- โœ… **Full feature access**: Access to latest models included in subscription -- โœ… **No API key management**: Uses OAuth tokens -- โœ… **Reusable authentication**: Capture once, use everywhere - -### Limitations -- โš ๏ธ **Less stable**: OAuth tokens may expire -- โš ๏ธ **Development-focused**: Not recommended for high-volume production -- โš ๏ธ **Setup required**: Requires interactive authentication +Uses personal Claude Code subscription for authentication. ### Setup Process @@ -38,10 +27,8 @@ This guide covers three authentication methods for using Claude with the webhook When the container starts: ```bash # In the container shell: -claude login -# Follow browser authentication flow -claude status # Verify authentication -exit # Save authentication state +claude --dangerously-skip-permissions # Follow authentication flow +exit # Save authentication state ``` #### 3. Test Captured Authentication @@ -56,35 +43,24 @@ cp -r ${CLAUDE_HUB_DIR:-~/.claude-hub}/* ~/.claude/ # Option B: Mount in docker-compose # Update docker-compose.yml: -# - ./${CLAUDE_HUB_DIR:-~/.claude-hub}:/home/node/.claude:ro +# - ./${CLAUDE_HUB_DIR:-~/.claude-hub}:/home/node/.claude ``` #### 5. Verify Setup ```bash -# Test webhook with your subscription -node cli/webhook-cli.js --repo "owner/repo" --command "Test my Claude subscription" --url "http://localhost:8082" +node cli/webhook-cli.js --repo "owner/repo" --command "Test authentication" --url "http://localhost:8082" ``` ### Troubleshooting -- **OAuth tokens expire**: Re-run authentication setup when needed +- **Tokens expire**: Re-run authentication setup when needed - **File permissions**: Ensure `.credentials.json` is readable by container user - **Mount issues**: Verify correct path in docker-compose volume mounts --- -## ๐Ÿ”‘ Option 2: ANTHROPIC_API_KEY (Production/Team) +## ๐Ÿ”‘ Option 2: ANTHROPIC_API_KEY (Production) -**Best for:** Production environments, team usage, or when you need guaranteed stability and higher rate limits. - -### Advantages -- โœ… **Highly stable**: Direct API key authentication -- โœ… **Higher limits**: Production-grade rate limits -- โœ… **Simple setup**: Just set environment variable -- โœ… **Team-friendly**: Multiple developers can use same key - -### Limitations -- ๐Ÿ’ฐ **High costs**: Pay-per-use pricing can be expensive -- ๐Ÿ”’ **Requires API access**: Need Anthropic Console access +Direct API key authentication for production environments. ### Setup Process @@ -112,26 +88,13 @@ node cli/webhook-cli.js --repo "owner/repo" --command "Test API key authenticati ### Best Practices - **Key rotation**: Regularly rotate API keys - **Environment security**: Never commit keys to version control -- **Usage monitoring**: Monitor API usage and costs -- **Rate limiting**: Implement appropriate rate limiting for your use case +- **Usage monitoring**: Monitor API usage through Anthropic Console --- ## โ˜๏ธ Option 3: AWS Bedrock (Enterprise) -**Best for:** Enterprise deployments, AWS-integrated environments, or when you need the highest stability and compliance. - -### Advantages -- โœ… **Enterprise-grade**: Highest stability and reliability -- โœ… **AWS integration**: Works with existing AWS infrastructure -- โœ… **Compliance**: Meets enterprise security requirements -- โœ… **Cost predictable**: More predictable pricing models -- โœ… **Regional deployment**: Data residency control - -### Limitations -- ๐Ÿ”ง **Complex setup**: Requires AWS configuration -- ๐Ÿ“‹ **AWS knowledge**: Requires familiarity with AWS services -- ๐Ÿข **Enterprise-focused**: May be overkill for individual developers +AWS-integrated Claude access for enterprise deployments. ### Setup Process @@ -160,7 +123,6 @@ AWS_PROFILE=claude-webhook #### 3. Verify Bedrock Access ```bash -# Test AWS Bedrock access aws bedrock list-foundation-models --region us-east-1 ``` @@ -174,15 +136,9 @@ docker compose restart webhook node cli/webhook-cli.js --repo "owner/repo" --command "Test Bedrock authentication" --url "http://localhost:8082" ``` -### Available Models -- `us.anthropic.claude-3-7-sonnet-20250219-v1:0` - Latest Claude 3.5 Sonnet -- `us.anthropic.claude-3-5-haiku-20241022-v1:0` - Claude 3.5 Haiku (faster/cheaper) -- `us.anthropic.claude-3-opus-20240229-v1:0` - Claude 3 Opus (most capable) - ### Best Practices - **IAM policies**: Use minimal required permissions -- **Regional selection**: Choose region closest to your users -- **Cost monitoring**: Set up CloudWatch billing alerts +- **Regional selection**: Choose appropriate AWS region - **Access logging**: Enable CloudTrail for audit compliance --- @@ -217,40 +173,15 @@ AWS_PROFILE=your-profile-name --- -## ๐Ÿ“Š Cost Comparison - -### Setup Container (Personal/Development) -- **Claude Max 5x**: $100/month (5x Pro usage limits, includes Claude Code) - - ~225 messages every 5 hours for short conversations - - ~50-200 Claude Code prompts every 5 hours -- **Claude Max 20x**: $200/month (20x Pro usage limits, includes Claude Code) - - ~900 messages every 5 hours for short conversations - - ~200-800 Claude Code prompts every 5 hours -- **Perfect for**: Individual developers, hobbyists, development workflows - -### ANTHROPIC_API_KEY (Production) -- **Pricing**: Pay-per-token usage -- **Claude 3.5 Sonnet**: ~$15 per million tokens -- **High volume**: Can easily exceed $100s/month -- **Perfect for**: Production applications, team environments - -### AWS Bedrock (Enterprise) -- **Pricing**: Pay-per-token with enterprise features -- **Claude 3.5 Sonnet**: Similar to API pricing -- **Additional costs**: AWS infrastructure, data transfer -- **Perfect for**: Enterprise deployments, compliance requirements - ---- - ## ๐Ÿ› ๏ธ Switching Between Methods -You can easily switch between authentication methods by updating your `.env` file: +You can switch between authentication methods by updating your `.env` file: ```bash # Development with personal subscription # Comment out API key, ensure ~/.claude is mounted # ANTHROPIC_API_KEY= -# Mount: ~/.claude:/home/node/.claude:ro +# Mount: ~/.claude:/home/node/.claude # Production with API key ANTHROPIC_API_KEY=sk-ant-your-production-key @@ -270,18 +201,13 @@ AWS_PROFILE=production-claude 1. Check environment variables are set correctly 2. Verify API keys are valid and not expired 3. For Bedrock: Ensure AWS credentials have correct permissions -4. For setup container: Re-run authentication if OAuth tokens expired +4. For setup container: Re-run authentication if tokens expired ### Rate Limiting -- **API Key**: Contact Anthropic for rate limit increases +- **API Key**: Contact Anthropic for rate limit information - **Bedrock**: Configure AWS throttling settings - **Setup Container**: Limited by subscription tier -### Cost Monitoring -- **API Key**: Monitor usage in Anthropic Console -- **Bedrock**: Set up AWS billing alerts -- **Setup Container**: Covered by subscription - --- ## ๐Ÿ“š Additional Resources @@ -293,20 +219,4 @@ AWS_PROFILE=production-claude --- -## ๐ŸŽฏ Recommendations by Use Case - -### Individual Developer -- **Start with**: Setup Container (use your Claude Max 5x or 20x subscription) -- **Upgrade to**: API Key if you need higher stability - -### Small Team -- **Recommended**: ANTHROPIC_API_KEY with cost monitoring -- **Alternative**: Multiple setup containers for development - -### Enterprise -- **Recommended**: AWS Bedrock with full compliance setup -- **Alternative**: ANTHROPIC_API_KEY with enterprise support contract - ---- - -*This guide covers all authentication methods for the Claude GitHub Webhook service. Choose the method that best fits your needs, budget, and technical requirements.* \ No newline at end of file +*This guide covers all authentication methods for the Claude GitHub Webhook service. Choose the method that best fits your technical requirements.* \ No newline at end of file diff --git a/docs/setup-container-guide.md b/docs/setup-container-guide.md index ab91cdd..3e434ac 100644 --- a/docs/setup-container-guide.md +++ b/docs/setup-container-guide.md @@ -6,7 +6,7 @@ The setup container method captures Claude CLI authentication state for use in a Claude CLI requires interactive authentication. This container approach captures the authentication state from an interactive session and makes it available for automated use. -**Prerequisites**: Claude Code access requires Claude Max subscriptions. Claude Pro plans do not include Claude Code access. +**Prerequisites**: Requires active Claude Code subscription. ## How It Works @@ -21,7 +21,7 @@ graph TD ### 1. Interactive Authentication - Clean container environment with Claude CLI installed -- User runs `claude login` and completes browser authentication +- User runs `claude --dangerously-skip-permissions` and completes authentication - OAuth tokens and session data stored in `~/.claude` ### 2. State Capture @@ -30,7 +30,7 @@ graph TD - Preserves all authentication context ### 3. Production Mount -- Captured authentication mounted read-only in production containers +- Captured authentication mounted in production containers - Working copy created for each execution to avoid state conflicts - OAuth tokens used automatically by Claude CLI @@ -83,7 +83,7 @@ The setup container captures all essential Claude authentication files: ## Token Lifecycle and Management ### Token Expiration Timeline -Based on testing, Claude OAuth tokens typically expire within **8-12 hours**: +Claude OAuth tokens typically expire within **8-12 hours**: - **Access tokens**: Short-lived (8-12 hours) - **Refresh tokens**: Longer-lived but also expire - **Automatic refresh**: Claude CLI attempts to refresh when needed @@ -115,8 +115,7 @@ However, refresh tokens themselves eventually expire, requiring **full re-authen - Monitor for expired token errors in logs **Re-authentication** -- Required when OAuth tokens expire (typically every few days to weeks) -- Refresh tokens also expire and require full re-authentication +- Required when OAuth tokens expire - Test authentication validity after updates ### Current Limitations @@ -139,17 +138,6 @@ However, refresh tokens themselves eventually expire, requiring **full re-authen ./claude-auth-test โ†’ test container ``` -### Team Sharing -```bash -# Capture authentication -./scripts/setup/setup-claude-interactive.sh - -# Share auth directory (be cautious with tokens) -tar -czf claude-auth.tar.gz ${CLAUDE_HUB_DIR:-~/.claude-hub}/ - -# Deploy to team environments -``` - ## Security Considerations ### Token Protection @@ -158,7 +146,7 @@ tar -czf claude-auth.tar.gz ${CLAUDE_HUB_DIR:-~/.claude-hub}/ - Rotate regularly by re-authenticating ### Container Security -- Mount authentication read-only +- Mount authentication with appropriate permissions - Use minimal container privileges - Avoid logging sensitive data @@ -176,7 +164,7 @@ tar -czf claude-auth.tar.gz ${CLAUDE_HUB_DIR:-~/.claude-hub}/ # Verify token validity docker run --rm -v "./${CLAUDE_HUB_DIR:-~/.claude-hub}:/home/node/.claude:ro" \ - claude-setup:latest claude status + claude-setup:latest claude --dangerously-skip-permissions ``` ### Refresh Workflow @@ -196,7 +184,7 @@ docker compose restart webhook #### 1. Empty .credentials.json **Symptom**: Authentication fails, file exists but is 0 bytes **Cause**: Interactive authentication wasn't completed -**Solution**: Re-run setup container and complete browser flow +**Solution**: Re-run setup container and complete authentication flow #### 2. Permission Errors **Symptom**: "Permission denied" accessing .credentials.json @@ -224,53 +212,12 @@ docker run --rm -v "$(pwd)/${CLAUDE_HUB_DIR:-~/.claude-hub}:/tmp/auth:ro" \ --entrypoint="" claude-setup:latest \ bash -c "cp -r /tmp/auth /home/node/.claude && sudo -u node env HOME=/home/node \ - /usr/local/share/npm-global/bin/claude --print 'test'" + /usr/local/share/npm-global/bin/claude --dangerously-skip-permissions --print 'test'" # Verify OAuth tokens cat ${CLAUDE_HUB_DIR:-~/.claude-hub}/.credentials.json | jq '.claudeAiOauth' ``` - -### Community Contributions -- **Authentication sharing**: Secure team auth distribution -- **Cloud storage**: Store auth in encrypted cloud storage -- **CI/CD integration**: Automated auth setup in pipelines - -## Cost Analysis for $200/month Users - -### Traditional API Approach -- **Claude 3.5 Sonnet**: ~$15 per million tokens -- **Heavy usage**: Easily $500+ per month -- **Usage anxiety**: Every request costs money - -### Setup Container Approach -- **Fixed cost**: $200/month for Claude 20x -- **Unlimited usage**: Within subscription limits -- **Peace of mind**: No per-request charging - -### Break-even Analysis -If you would use more than ~13 million tokens per month, the setup container approach with Claude 20x subscription becomes cost-effective while providing better performance and unlimited usage. - -## Real-world Applications - -### Development Workflows -- **Code review automation**: PR reviews without API costs -- **Issue auto-tagging**: Unlimited issue processing -- **Documentation generation**: Bulk doc creation -- **Test case generation**: Comprehensive test coverage - -### Personal Projects -- **GitHub automation**: Personal repository management -- **Content creation**: Blog posts, documentation -- **Learning projects**: Educational coding assistance -- **Prototyping**: Rapid development iteration - -### Small Business -- **Customer support**: Automated responses -- **Content moderation**: Community management -- **Documentation**: Internal knowledge base -- **Training**: Employee onboarding assistance - --- -*The setup container approach democratizes Claude automation for subscription users, making enterprise-level AI automation accessible at subscription pricing.* \ No newline at end of file +*The setup container approach provides a technical solution for capturing and reusing Claude CLI authentication in automated environments.* \ No newline at end of file diff --git a/scripts/setup/setup-claude-interactive.sh b/scripts/setup/setup-claude-interactive.sh index e41ac1a..be040c4 100755 --- a/scripts/setup/setup-claude-interactive.sh +++ b/scripts/setup/setup-claude-interactive.sh @@ -22,10 +22,9 @@ echo "" echo "๐Ÿš€ Starting interactive Claude authentication container..." echo "" echo "IMPORTANT: This will open an interactive shell where you can:" -echo " 1. Run 'claude login' to authenticate" -echo " 2. Follow the browser-based authentication flow" -echo " 3. Test with 'claude status' to verify authentication" -echo " 4. Type 'exit' when done to preserve authentication state" +echo " 1. Run 'claude --dangerously-skip-permissions' to authenticate" +echo " 2. Follow the authentication flow" +echo " 3. Type 'exit' when done to preserve authentication state" echo "" echo "The authenticated ~/.claude directory will be saved to:" echo " $AUTH_OUTPUT_DIR" @@ -57,11 +56,11 @@ if [ -f "$AUTH_OUTPUT_DIR/.credentials.json" ] || [ -f "$AUTH_OUTPUT_DIR/setting else echo "โš ๏ธ No authentication files found. You may need to:" echo " 1. Run the container again and complete the authentication flow" - echo " 2. Ensure you ran 'claude login' and completed the browser authentication" - echo " 3. Check that you have an active Claude Max or Pro subscription" + echo " 2. Ensure you ran 'claude --dangerously-skip-permissions' and completed authentication" + echo " 3. Check that you have an active Claude Code subscription" fi echo "" echo "๐Ÿงช Testing authentication..." echo "You can test the captured authentication with:" -echo " docker run --rm -v \"$AUTH_OUTPUT_DIR:/home/node/.claude:ro\" claude-setup:latest claude status" \ No newline at end of file +echo " docker run --rm -v \"$AUTH_OUTPUT_DIR:/home/node/.claude:ro\" claude-setup:latest claude --dangerously-skip-permissions --print 'test'" \ No newline at end of file diff --git a/test/unit/services/claudeService.test.js b/test/unit/services/claudeService.test.js index fea8afc..8a3ddeb 100644 --- a/test/unit/services/claudeService.test.js +++ b/test/unit/services/claudeService.test.js @@ -133,6 +133,68 @@ describe('Claude Service', () => { } }); + test('processCommand should mount authentication directory correctly', async () => { + // Save original function for restoration + const originalProcessCommand = claudeService.processCommand; + + // Create a testing implementation that checks Docker args + claudeService.processCommand = async options => { + // Set test environment variables + const originalNodeEnv = process.env.NODE_ENV; + process.env.NODE_ENV = 'production'; + process.env.CLAUDE_AUTH_HOST_DIR = '/test/auth/dir'; + + // Mock the Docker inspect to succeed + execFileSync.mockImplementation((cmd, args, _options) => { + if (args[0] === 'inspect') return '{}'; + return 'mocked output'; + }); + + // Configure execFileAsync mock to capture Docker args + const execFileAsync = promisify(require('child_process').execFile); + execFileAsync.mockImplementation(async (cmd, args, _options) => { + // Check that authentication directory is mounted correctly + const dockerArgs = args; + const volumeArgIndex = dockerArgs.findIndex(arg => arg === '-v'); + if (volumeArgIndex !== -1) { + const volumeMount = dockerArgs[volumeArgIndex + 1]; + expect(volumeMount).toBe('/test/auth/dir:/home/node/.claude'); + } + + return { + stdout: 'Claude response from container', + stderr: '' + }; + }); + + // Call the original implementation to test it + const result = await originalProcessCommand(options); + + // Restore env + process.env.NODE_ENV = originalNodeEnv; + delete process.env.CLAUDE_AUTH_HOST_DIR; + + return result; + }; + + try { + // Call the overridden function + await claudeService.processCommand({ + repoFullName: 'test/repo', + issueNumber: 123, + command: 'Test command', + isPullRequest: false + }); + + // Verify execFileAsync was called (authentication mount logic executed) + const execFileAsync = promisify(require('child_process').execFile); + expect(execFileAsync).toHaveBeenCalled(); + } finally { + // Restore the original function + claudeService.processCommand = originalProcessCommand; + } + }); + test('processCommand should handle errors properly', async () => { // Save original function for restoration const originalProcessCommand = claudeService.processCommand;