@sarvy2k/acme-client-proxy/README.md

ACME client with SOCKS proxy support for rotating IP addresses

# @sarvy2k/acme-client-proxy

[![npm version](https://img.shields.io/npm/v/@sarvy2k/acme-client-proxy.svg)](https://www.npmjs.com/package/@sarvy2k/acme-client-proxy)
[![npm downloads](https://img.shields.io/npm/dm/@sarvy2k/acme-client-proxy.svg)](https://www.npmjs.com/package/@sarvy2k/acme-client-proxy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**ACME client with SOCKS proxy support for rotating IP addresses**

A fork of [node-acme-client](https://github.com/publishlab/node-acme-client) with added proxy rotation capabilities to help distribute ACME requests across multiple IP addresses, reducing rate limiting and improving reliability.

## 🚀 Features

- ✅ **SOCKS Proxy Support** - Route all ACME requests through SOCKS proxies
- ✅ **IP Rotation** - Use different IP addresses for each request
- ✅ **Rate Limit Distribution** - Spread load across multiple IPs
- ✅ **TypeScript Support** - Full TypeScript definitions included
- ✅ **Drop-in Replacement** - Compatible with original acme-client API
- ✅ **ES6/CommonJS** - Works with both import styles
- ✅ **All ACME Operations** - Directory, account, order, challenge, certificate operations

## 📦 Installation

```bash
npm install @sarvy2k/acme-client-proxy
```

## 🔧 Usage

### Basic Usage with Proxy

```javascript
const acme = require('@sarvy2k/acme-client-proxy');
const { SocksProxyAgent } = require('socks-proxy-agent');

// Create proxy agent
const proxyAgent = new SocksProxyAgent('socks5://127.0.0.1:1080');

// Create ACME client with proxy
const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
    proxyAgent: proxyAgent  // ← New proxy option!
});

// All ACME operations now use the proxy
const directory = await client.getDirectory();
const account = await client.createAccount({
    termsOfServiceAgreed: true
});
```

### ES6 Import Style

```javascript
import acme from '@sarvy2k/acme-client-proxy';
import { SocksProxyAgent } from 'socks-proxy-agent';

const proxyAgent = new SocksProxyAgent('socks5://127.0.0.1:1080');
const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
    proxyAgent: proxyAgent
});
```

### Rotating Proxies

```javascript
const acme = require('@sarvy2k/acme-client-proxy');
const { SocksProxyAgent } = require('socks-proxy-agent');

// Rotate through multiple proxies
const proxies = [
    'socks5://proxy1.example.com:1080',
    'socks5://proxy2.example.com:1080',
    'socks5://proxy3.example.com:1080'
];

function getRandomProxy() {
    const proxyUrl = proxies[Math.floor(Math.random() * proxies.length)];
    return new SocksProxyAgent(proxyUrl);
}

// Use different proxy for each request
const client1 = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
    proxyAgent: getRandomProxy()
});

const client2 = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
    proxyAgent: getRandomProxy()
});
```

## 🔗 Proxy Agent Options

The `proxyAgent` option accepts any HTTP/HTTPS agent:

- `SocksProxyAgent` from `socks-proxy-agent`
- `HttpsProxyAgent` from `https-proxy-agent`
- `HttpProxyAgent` from `http-proxy-agent`
- Custom agents implementing the agent interface

### SOCKS5 Proxy

```javascript
const { SocksProxyAgent } = require('socks-proxy-agent');

const proxyAgent = new SocksProxyAgent('socks5://user:pass@proxy.example.com:1080');
```

### HTTP/HTTPS Proxy

```javascript
const { HttpsProxyAgent } = require('https-proxy-agent');
const { HttpProxyAgent } = require('http-proxy-agent');

const httpsProxyAgent = new HttpsProxyAgent('http://proxy.example.com:8080');
const httpProxyAgent = new HttpProxyAgent('http://proxy.example.com:8080');
```

## 📋 API Changes

### New Client Option

```typescript
interface ClientOptions {
    directoryUrl: string;
    accountKey: PrivateKeyBuffer | PrivateKeyString;
    accountUrl?: string;
    externalAccountBinding?: ClientExternalAccountBindingOptions;
    backoffAttempts?: number;
    backoffMin?: number;
    backoffMax?: number;
    proxyAgent?: any; // HTTP/HTTPS agent for proxy requests
}
```

### All Operations Use Proxy

Every ACME operation automatically uses the provided proxy agent:
- Directory requests
- Account creation/updates
- Order creation
- Challenge verification
- Certificate issuance
- Certificate revocation

## 🧪 Testing

The package includes comprehensive testing to verify proxy usage:

```javascript
// Test that all requests use proxy
const axiosModule = require('@sarvy2k/acme-client-proxy/src/axios');

// Intercept requests to verify proxy usage
const originalRequest = axiosModule.request;
axiosModule.request = function (config) {
    const hasProxy = !!(config.httpsAgent || config.httpAgent);
    console.log(`Request to ${config.url}: ${hasProxy ? 'WITH PROXY' : 'NO PROXY'}`);
    return originalRequest.call(this, config);
};
```

## 🔄 Migration from Original acme-client

This package is a drop-in replacement for the original `acme-client`. Simply:

1. Replace the package:
   ```bash
   npm uninstall acme-client
   npm install @sarvy2k/acme-client-proxy
   ```

2. Update imports:
   ```javascript
   // Before
   const acme = require('acme-client');
   
   // After
   const acme = require('@sarvy2k/acme-client-proxy');
   ```

3. Add proxy support (optional):
   ```javascript
   const client = new acme.Client({
       directoryUrl: acme.directory.letsencrypt.staging,
       accountKey: accountPrivateKey,
       proxyAgent: new SocksProxyAgent('socks5://127.0.0.1:1080') // ← Add this
   });
   ```

## 📚 Original acme-client Features

This package includes all features from the original [node-acme-client](https://github.com/publishlab/node-acme-client):

- **ACME v2 Support** - Full RFC 8555 compliance
- **Multiple CAs** - Let's Encrypt, ZeroSSL, Google, Buypass
- **Challenge Types** - HTTP-01, DNS-01, TLS-ALPN-01
- **Auto Mode** - Simplified certificate issuance
- **Cryptography** - RSA and ECDSA key support
- **TypeScript** - Complete type definitions

## 🛠️ Development

### Building

```bash
git clone https://github.com/dsouzaalan/acme-client-proxy.git
cd acme-client-proxy
npm install
npm test
```

### Testing Proxy Integration

```bash
# Test basic proxy functionality
npm run test-proxy

# Test comprehensive proxy usage
npm run test-proxy-comprehensive
```

## 📄 License

MIT - Same as original acme-client

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 🔗 Links

- **NPM Package**: https://www.npmjs.com/package/@sarvy2k/acme-client-proxy
- **GitHub Repository**: https://github.com/dsouzaalan/acme-client-proxy
- **Original acme-client**: https://github.com/publishlab/node-acme-client
- **ACME RFC 8555**: https://datatracker.ietf.org/doc/html/rfc8555

## ⚠️ Important Notes

- **Rate Limiting**: While proxy rotation helps distribute load, always respect ACME provider rate limits
- **Proxy Reliability**: Ensure your proxy servers are reliable and have good uptime
- **Security**: Use trusted proxy providers and secure authentication
- **Compliance**: Follow ACME provider terms of service and usage policies

## 🆕 Changelog

### v5.4.0-proxy.3
- Fixed ES6 module imports
- Added axios subpath export for testing
- Improved package.json exports configuration

### v5.4.0-proxy.2
- Added ES6 module support
- Fixed CommonJS/ES6 compatibility
- Updated package structure

### v5.4.0-proxy.1
- Initial release with SOCKS proxy support
- Fork of node-acme-client v5.4.0
- Added proxyAgent option to Client constructor
- All ACME operations route through provided proxy agent