smartproxy/readme.plan.md

SmartProxy ACME Simplification Plan

Overview

This plan addresses the certificate acquisition confusion in SmartProxy v19.0.0 and proposes simplifications to make ACME configuration more intuitive.

Current Issues

1. ACME configuration placement is confusing (route-level vs top-level)
2. SmartAcme initialization logic is complex and error-prone
3. Documentation doesn't clearly explain the correct configuration format
4. Error messages like "SmartAcme not initialized" are not helpful

Proposed Simplifications

1. Support Both Configuration Styles

• Reread CLAUDE.md before starting implementation
• Accept ACME config at both top-level and route-level
• Use top-level ACME config as defaults for all routes
• Allow route-level ACME config to override top-level defaults
• Make email field required when any route uses certificate: 'auto'

2. Improve SmartAcme Initialization

• Initialize SmartAcme when top-level ACME config exists with email
• Initialize SmartAcme when any route has certificate: 'auto'
• Provide clear error messages when initialization fails
• Add debug logging for ACME initialization steps

3. Simplify Certificate Configuration

• Create helper method to validate ACME configuration
• Auto-detect when port 80 is needed for challenges
• Provide sensible defaults for ACME settings
• Add configuration examples in documentation

4. Update Documentation

• Create clear examples for common ACME scenarios
• Document the configuration hierarchy (top-level vs route-level)
• Add troubleshooting guide for common certificate issues
• Include migration guide from v18 to v19

5. Add Configuration Helpers

• Create SmartProxyConfig.fromSimple() helper for basic setups (part of validation)
• Add validation for common misconfigurations
• Provide warning messages for deprecated patterns
• Include auto-correction suggestions

Implementation Steps

Phase 1: Configuration Support ✅

1. ✅ Update ISmartProxyOptions interface to clarify ACME placement
2. ✅ Modify SmartProxy constructor to handle top-level ACME config
3. ✅ Update SmartCertManager to accept global ACME defaults
4. ✅ Add configuration validation and helpful error messages

Phase 2: Testing ✅

1. ✅ Add tests for both configuration styles
2. ✅ Test ACME initialization with various configurations
3. ✅ Verify certificate acquisition works in all scenarios
4. ✅ Test error handling and messaging

Phase 3: Documentation ✅

1. ✅ Update main README with clear ACME examples
2. ✅ Create dedicated certificate-management.md guide
3. ✅ Add migration guide for v18 to v19 users
4. ✅ Include troubleshooting section

Example Simplified Configuration

// Simplified configuration with top-level ACME
const proxy = new SmartProxy({
  // Global ACME settings (applies to all routes with certificate: 'auto')
  acme: {
    email: 'ssl@example.com',
    useProduction: false,
    port: 80  // Automatically listened on when needed
  },
  
  routes: [
    {
      name: 'secure-site',
      match: { domains: 'example.com', ports: 443 },
      action: {
        type: 'forward',
        target: { host: 'localhost', port: 8080 },
        tls: {
          mode: 'terminate',
          certificate: 'auto'  // Uses global ACME settings
        }
      }
    }
  ]
});

// Or with route-specific ACME override
const proxy = new SmartProxy({
  routes: [
    {
      name: 'special-site',
      match: { domains: 'special.com', ports: 443 },
      action: {
        type: 'forward',
        target: { host: 'localhost', port: 8080 },
        tls: {
          mode: 'terminate',
          certificate: 'auto',
          acme: {  // Route-specific override
            email: 'special@example.com',
            useProduction: true
          }
        }
      }
    }
  ]
});

Success Criteria ✅

1. ✅ Users can configure ACME at top-level for all routes
2. ✅ Clear error messages guide users to correct configuration
3. ✅ Certificate acquisition works with minimal configuration
4. ✅ Documentation clearly explains all configuration options
5. ✅ Migration from v18 to v19 is straightforward

Timeline

• Phase 1: 2-3 days
• Phase 2: 1-2 days
• Phase 3: 1 day

Total estimated time: 5-6 days

Notes

• Maintain backward compatibility with existing route-level ACME config
• Consider adding a configuration wizard for interactive setup
• Explore integration with popular DNS providers for DNS-01 challenges
• Add metrics/monitoring for certificate renewal status