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
- [x] Reread CLAUDE.md before starting implementation
- [x] Accept ACME config at both top-level and route-level
- [x] Use top-level ACME config as defaults for all routes
- [x] Allow route-level ACME config to override top-level defaults
- [x] Make email field required when any route uses `certificate: 'auto'`

### 2. Improve SmartAcme Initialization
- [x] Initialize SmartAcme when top-level ACME config exists with email
- [x] Initialize SmartAcme when any route has `certificate: 'auto'`
- [x] Provide clear error messages when initialization fails
- [x] Add debug logging for ACME initialization steps

### 3. Simplify Certificate Configuration
- [x] Create helper method to validate ACME configuration
- [x] Auto-detect when port 80 is needed for challenges
- [x] Provide sensible defaults for ACME settings
- [x] Add configuration examples in documentation

### 4. Update Documentation
- [x] Create clear examples for common ACME scenarios
- [x] Document the configuration hierarchy (top-level vs route-level)
- [x] Add troubleshooting guide for common certificate issues
- [x] Include migration guide from v18 to v19

### 5. Add Configuration Helpers
- [x] Create `SmartProxyConfig.fromSimple()` helper for basic setups (part of validation)
- [x] Add validation for common misconfigurations
- [x] Provide warning messages for deprecated patterns
- [x] 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

```typescript
// 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