docs: clean up authentication documentation and add test coverage

- Remove TOS violations and marketing copy from authentication guides - Fix Claude CLI command references to use --dangerously-skip-permissions - Update setup scripts with correct command syntax - Add test coverage for Docker authentication mount path logic - Focus documentation on technical implementation details 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-05-31 12:48:32 -05:00
parent 41903540ea
commit f5f7520588
5 changed files with 109 additions and 194 deletions
--- 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
--- 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.*
+*This guide covers all authentication methods for the Claude GitHub Webhook service. Choose the method that best fits your technical requirements.*
--- 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.*
+*The setup container approach provides a technical solution for capturing and reusing Claude CLI authentication in automated environments.*
--- 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"
+echo "  docker run --rm -v \"$AUTH_OUTPUT_DIR:/home/node/.claude:ro\" claude-setup:latest claude --dangerously-skip-permissions --print 'test'"
--- 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;