certctl-cli 1.0.5 → 1.0.10

package/API.md

@@ -0,0 +1,767 @@
+# Certctl Programmatic API 使用指南
+
+如果你在 Node.js 项目中需要通过代码调用证书申请功能，有以下两种方式：
+
+---
+
+## 方式一：通过子进程调用 CLI（推荐，当前可用）
+
+这是目前最稳定的方式，直接调用 `certctl` 命令。
+
+### 安装
+
+```bash
+npm install certctl-cli
+```
+
+### 基础用法
+
+```javascript
+const { spawn } = require('child_process');
+const path = require('path');
+
+// 获取 certctl 二进制路径
+function getCertctlPath() {
+  return path.join(__dirname, 'node_modules', '.bin', 'certctl');
+}
+
+/**
+ * 申请证书
+ * @param {Object} options - 配置选项
+ * @param {string} options.domain - 域名 (必填)
+ * @param {string} options.email - 邮箱 (必填)
+ * @param {string} options.output - 输出目录 (可选，默认 ./certs)
+ * @param {string} options.dns - DNS 提供商 (可选: aliyun/tencentcloud)
+ * @param {Object} options.credentials - DNS 凭证 (可选)
+ */
+function applyCertificate(options) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      'apply',
+      '-d', options.domain,
+      '-e', options.email,
+      '-o', options.output || './certs'
+    ];
+
+    // 自动 DNS 验证
+    if (options.dns) {
+      args.push('--dns', options.dns);
+      
+      if (options.dns === 'aliyun' && options.credentials) {
+        args.push(
+          '--ali-key', options.credentials.accessKeyId,
+          '--ali-secret', options.credentials.accessKeySecret
+        );
+      }
+      
+      if (options.dns === 'tencentcloud' && options.credentials) {
+        args.push(
+          '--tencent-id', options.credentials.secretId,
+          '--tencent-secret', options.credentials.secretKey
+        );
+      }
+    }
+
+    const certctl = spawn(getCertctlPath(), args, {
+      stdio: ['inherit', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    certctl.stdout.on('data', (data) => {
+      stdout += data.toString();
+      console.log(data.toString()); // 实时输出日志
+    });
+
+    certctl.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({
+          success: true,
+          domain: options.domain,
+          output: options.output || './certs',
+          stdout
+        });
+      } else {
+        reject(new Error(`证书申请失败: ${stderr || stdout}`));
+      }
+    });
+  });
+}
+
+// 使用示例
+async function main() {
+  try {
+    // 示例 1: 阿里云自动验证
+    const result = await applyCertificate({
+      domain: 'example.com',
+      email: 'admin@example.com',
+      output: './my-certs',
+      dns: 'aliyun',
+      credentials: {
+        accessKeyId: process.env.ALICLOUD_ACCESS_KEY,
+        accessKeySecret: process.env.ALICLOUD_SECRET_KEY
+      }
+    });
+    
+    console.log('证书申请成功:', result);
+    
+    // 证书文件位置
+    const certPath = `./my-certs/${result.domain}/${result.domain}.pem`;
+    const keyPath = `./my-certs/${result.domain}/${result.domain}.key`;
+    
+    console.log('证书路径:', certPath);
+    console.log('私钥路径:', keyPath);
+    
+  } catch (error) {
+    console.error('申请失败:', error.message);
+  }
+}
+
+main();
+```
+
+### 续期证书
+
+```javascript
+const { spawn } = require('child_process');
+
+function renewCertificate(domain, outputDir = './certs') {
+  return new Promise((resolve, reject) => {
+    const certctl = spawn('certctl', [
+      'renew',
+      '-d', domain,
+      '-o', outputDir
+    ], {
+      stdio: 'pipe'
+    });
+
+    let output = '';
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true, output });
+      } else {
+        reject(new Error(`续期失败: ${output}`));
+      }
+    });
+  });
+}
+
+// 使用
+renewCertificate('example.com', './my-certs')
+  .then(() => console.log('续期成功'))
+  .catch(err => console.error(err));
+```
+
+### 验证证书
+
+```javascript
+const { spawn } = require('child_process');
+
+function verifyCertificate(domain, certPath) {
+  return new Promise((resolve, reject) => {
+    const args = ['verify', '-d', domain];
+    if (certPath) {
+      args.push('-p', certPath);
+    }
+
+    const certctl = spawn('certctl', args, {
+      stdio: 'pipe'
+    });
+
+    let output = '';
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      resolve({
+        valid: code === 0,
+        output
+      });
+    });
+  });
+}
+
+// 使用
+verifyCertificate('example.com')
+  .then(result => {
+    console.log('验证结果:', result.valid ? '通过' : '失败');
+    console.log(result.output);
+  });
+```
+
+### 修复证书链
+
+```javascript
+const { spawn } = require('child_process');
+
+function fixCertificateChain(domain, certPath) {
+  return new Promise((resolve, reject) => {
+    const args = ['fix-chain'];
+    
+    if (certPath) {
+      args.push('-p', certPath);
+    } else if (domain) {
+      args.push('-d', domain);
+    }
+
+    const certctl = spawn('certctl', args, {
+      stdio: 'pipe'
+    });
+
+    let output = '';
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true, output });
+      } else {
+        reject(new Error(`修复失败: ${output}`));
+      }
+    });
+  });
+}
+```
+
+---
+
+## 方式二：完整 SDK（含自动续期和证书链验证）
+
+我们提供了完整的 SDK 封装，包含自动续期、证书链验证与修复等高级功能。
+
+### 安装
+
+```bash
+npm install certctl-cli
+```
+
+### 使用 SDK
+
+```javascript
+const { CertctlSDK } = require('certctl-cli/examples/certctl-sdk');
+
+// 创建 SDK 实例
+const sdk = new CertctlSDK({
+  email: 'admin@example.com',
+  outputDir: './certs',
+  
+  // DNS 配置（用于自动续期）
+  dns: {
+    provider: 'aliyun',
+    accessKeyId: process.env.ALI_KEY,
+    accessKeySecret: process.env.ALI_SECRET
+  },
+  
+  // 自动续期配置
+  autoRenew: true,              // 开启自动续期
+  renewBeforeDays: 30,          // 到期前30天续期
+  checkInterval: 24 * 60 * 60 * 1000,  // 每天检查
+});
+
+// 监听事件
+sdk.on('apply:success', ({ domain, certInfo }) => {
+  console.log(`✅ 证书申请成功: ${domain}`);
+});
+
+sdk.on('verify:fixing', ({ domain }) => {
+  console.log(`🔧 正在自动修复证书链: ${domain}`);
+});
+
+sdk.on('autoRenew:trigger', ({ domain, reason }) => {
+  console.log(`🔄 自动续期: ${domain} (${reason})`);
+});
+
+// 申请证书（自动验证并修复证书链）
+const result = await sdk.apply('example.com', {
+  verifyChain: true,    // 申请后验证证书链
+  autoFix: true,        // 链不完整时自动修复
+});
+
+// 返回结果
+// {
+//   success: true,
+//   domain: 'example.com',
+//   paths: { cert: '...', key: '...' },
+//   chainValid: true,      // 证书链是否完整
+//   chainLength: 2,        // 证书链长度
+//   expireDays: 89         // 剩余天数
+// }
+```
+
+### SDK 配置选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `email` | string | - | Let's Encrypt 账户邮箱 |
+| `outputDir` | string | './certs' | 证书输出目录 |
+| `autoRenew` | boolean | true | 是否开启自动续期 |
+| `renewBeforeDays` | number | 30 | 到期前多少天续期 |
+| `checkInterval` | number | 86400000 | 检查间隔（毫秒） |
+| `dns` | object | null | DNS 配置用于自动续期 |
+
+### SDK 方法
+
+#### `apply(domain, options)` - 申请证书
+
+```javascript
+const result = await sdk.apply('example.com', {
+  email: 'admin@example.com',      // 可选
+  verifyChain: true,                // 验证证书链
+  autoFix: true,                    // 自动修复
+  dns: { provider: 'aliyun', ... }  // 可选
+});
+```
+
+#### `verify(domain, options)` - 验证证书（含自动修复）
+
+```javascript
+const result = await sdk.verify('example.com', {
+  autoFix: true  // 验证失败时自动修复证书链
+});
+
+// 返回结果
+// {
+//   valid: true,           // 是否通过
+//   chainValid: true,      // 证书链完整
+//   chainLength: 2,
+//   expireDays: 89,
+//   domainMatch: true,
+//   notExpired: true
+// }
+```
+
+#### `renew(domain, options)` - 续期证书
+
+```javascript
+const result = await sdk.renew('example.com', {
+  autoFix: true   // 续期后自动修复
+});
+```
+
+#### `checkRenewal(domain)` - 检查是否需要续期
+
+```javascript
+const status = await sdk.checkRenewal('example.com');
+
+// 返回结果
+// {
+//   needRenew: false,      // 是否需要续期
+//   reason: '...',         // 原因
+//   expireDays: 89,
+//   chainValid: true
+// }
+```
+
+#### `startAutoRenew(domains)` - 启动自动续期服务
+
+```javascript
+// 启动自动续期监控
+sdk.startAutoRenew(['example.com', 'api.example.com']);
+
+// 服务会自动：
+// 1. 定期检查证书有效期
+// 2. 证书链不完整时自动修复
+// 3. 即将过期时自动续期
+// 4. 通过事件通知状态变化
+```
+
+#### `stopAutoRenew()` - 停止自动续期
+
+```javascript
+sdk.stopAutoRenew();
+```
+
+### SDK 事件
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `apply:success` | `{ domain, certInfo }` | 证书申请成功 |
+| `verify:fixing` | `{ domain }` | 正在修复证书链 |
+| `verify:success` | `{ domain, ... }` | 验证通过 |
+| `autoRenew:trigger` | `{ domain, reason }` | 触发自动续期 |
+| `autoRenew:error` | `{ domain, error }` | 自动续期失败 |
+
+### Express HTTP API + 自动续期完整示例
+
+```javascript
+const express = require('express');
+const { CertctlSDK } = require('certctl-cli/examples/certctl-sdk');
+
+const app = express();
+app.use(express.json());
+
+// 创建 SDK 实例
+const sdk = new CertctlSDK({
+  email: process.env.ACME_EMAIL,
+  outputDir: './certs',
+  autoRenew: true,
+  renewBeforeDays: 30,
+  dns: {
+    provider: 'aliyun',
+    accessKeyId: process.env.ALI_KEY,
+    accessKeySecret: process.env.ALI_SECRET
+  }
+});
+
+// 监听事件
+sdk.on('apply:success', ({ domain }) => console.log(`[${new Date().toISOString()}] 申请成功: ${domain}`));
+sdk.on('autoRenew:trigger', ({ domain, reason }) => console.log(`[${new Date().toISOString()}] 自动续期: ${domain} - ${reason}`));
+
+// API: 申请证书（自动验证并修复证书链）
+app.post('/api/certs/:domain', async (req, res) => {
+  try {
+    const result = await sdk.apply(req.params.domain, {
+      verifyChain: true,   // 验证证书链
+      autoFix: true        // 自动修复
+    });
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+// API: 验证证书（自动修复）
+app.get('/api/certs/:domain/verify', async (req, res) => {
+  const result = await sdk.verify(req.params.domain, { autoFix: true });
+  res.json(result);
+});
+
+// API: 检查续期状态
+app.get('/api/certs/:domain/renewal-status', async (req, res) => {
+  const result = await sdk.checkRenewal(req.params.domain);
+  res.json(result);
+});
+
+// 启动自动续期服务
+sdk.startAutoRenew(['example.com', 'api.example.com']);
+
+app.listen(3000, () => {
+  console.log('🚀 证书管理 API 已启动');
+});
+```
+
+### 示例文件位置
+
+安装后可在 `node_modules/certctl-cli/examples/` 找到：
+
+- `certctl-sdk.js` - 完整 SDK 源码
+- `sdk-usage.js` - SDK 使用示例
+- `express-server.js` - Express 集成示例
+- `basic-usage.js` - 基础调用示例
+
+---
+
+## TypeScript 类型定义
+
+如果你使用 TypeScript，以下是类型定义：
+
+```typescript
+// certctl.d.ts
+
+export interface ApplyOptions {
+  domain: string;
+  email: string;
+  output?: string;
+  dns?: 'aliyun' | 'tencentcloud';
+  credentials?: {
+    accessKeyId?: string;
+    accessKeySecret?: string;
+    secretId?: string;
+    secretKey?: string;
+  };
+  staging?: boolean;
+}
+
+export interface ApplyResult {
+  success: boolean;
+  domain: string;
+  output: string;
+  stdout: string;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  output: string;
+}
+
+export declare function applyCertificate(options: ApplyOptions): Promise<ApplyResult>;
+export declare function renewCertificate(domain: string, outputDir?: string): Promise<{ success: boolean; output: string }>;
+export declare function verifyCertificate(domain: string, certPath?: string): Promise<VerifyResult>;
+export declare function fixCertificateChain(domain?: string, certPath?: string): Promise<{ success: boolean; output: string }>;
+```
+
+---
+
+## 完整项目示例
+
+```
+my-project/
+├── src/
+│   ├── certctl-wrapper.js    # 封装 certctl 调用
+│   ├── server.js             # 你的应用
+│   └── config.js
+├── certs/                    # 证书输出目录
+├── package.json
+└── .env
+```
+
+### certctl-wrapper.js
+
+```javascript
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+class CertctlWrapper {
+  constructor(options = {}) {
+    this.email = options.email;
+    this.outputDir = options.outputDir || './certs';
+    this.binaryPath = options.binaryPath || 'certctl';
+  }
+
+  _spawn(args) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(this.binaryPath, args, {
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve({ stdout, stderr, code });
+        } else {
+          reject(new Error(`Process exited with code ${code}: ${stderr || stdout}`));
+        }
+      });
+    });
+  }
+
+  async apply(domain, dnsOptions = null) {
+    const args = [
+      'apply',
+      '-d', domain,
+      '-e', this.email,
+      '-o', this.outputDir
+    ];
+
+    if (dnsOptions) {
+      args.push('--dns', dnsOptions.provider);
+      
+      if (dnsOptions.provider === 'aliyun') {
+        args.push(
+          '--ali-key', dnsOptions.accessKeyId,
+          '--ali-secret', dnsOptions.accessKeySecret
+        );
+      } else if (dnsOptions.provider === 'tencentcloud') {
+        args.push(
+          '--tencent-id', dnsOptions.secretId,
+          '--tencent-secret', dnsOptions.secretKey
+        );
+      }
+    }
+
+    const result = await this._spawn(args);
+    
+    return {
+      success: true,
+      domain,
+      paths: {
+        cert: path.join(this.outputDir, domain, `${domain}.pem`),
+        key: path.join(this.outputDir, domain, `${domain}.key`)
+      },
+      output: result.stdout
+    };
+  }
+
+  async renew(domain) {
+    const args = ['renew', '-d', domain, '-o', this.outputDir];
+    const result = await this._spawn(args);
+    return { success: true, output: result.stdout };
+  }
+
+  async verify(domain) {
+    const args = ['verify', '-d', domain];
+    try {
+      const result = await this._spawn(args);
+      return { valid: true, output: result.stdout };
+    } catch (err) {
+      return { valid: false, output: err.message };
+    }
+  }
+
+  async fixChain(domain) {
+    const args = ['fix-chain', '-d', domain];
+    const result = await this._spawn(args);
+    return { success: true, output: result.stdout };
+  }
+
+  getCertificatePaths(domain) {
+    return {
+      cert: path.join(this.outputDir, domain, `${domain}.pem`),
+      key: path.join(this.outputDir, domain, `${domain}.key`)
+    };
+  }
+
+  exists(domain) {
+    const paths = this.getCertificatePaths(domain);
+    return fs.existsSync(paths.cert) && fs.existsSync(paths.key);
+  }
+}
+
+module.exports = { CertctlWrapper };
+```
+
+### server.js
+
+```javascript
+const { CertctlWrapper } = require('./certctl-wrapper');
+const express = require('express');
+
+const app = express();
+const certClient = new CertctlWrapper({
+  email: process.env.ACME_EMAIL,
+  outputDir: './certs'
+});
+
+// API: 申请证书
+app.post('/api/certs/:domain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    
+    // 检查是否已存在
+    if (certClient.exists(domain)) {
+      return res.json({ 
+        success: true, 
+        message: '证书已存在',
+        paths: certClient.getCertificatePaths(domain)
+      });
+    }
+
+    // 申请证书
+    const result = await certClient.apply(domain, {
+      provider: 'aliyun',
+      accessKeyId: process.env.ALI_KEY,
+      accessKeySecret: process.env.ALI_SECRET
+    });
+
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+// API: 获取证书信息
+app.get('/api/certs/:domain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    const verifyResult = await certClient.verify(domain);
+    
+    res.json({
+      domain,
+      exists: certClient.exists(domain),
+      valid: verifyResult.valid,
+      paths: certClient.getCertificatePaths(domain)
+    });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+---
+
+## 常见问题
+
+### Q: 如何在 Docker 中使用？
+
+```dockerfile
+FROM node:18-alpine
+
+# 安装 certctl
+RUN npm install -g certctl-cli
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+CMD ["node", "server.js"]
+```
+
+### Q: 如何监控证书到期？
+
+```javascript
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+// 定期检查证书有效期
+function checkCertExpiry(domain, certPath) {
+  return new Promise((resolve) => {
+    const certctl = spawn('certctl', ['verify', '-d', domain, '-p', certPath]);
+    let output = '';
+    
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+    
+    certctl.on('close', () => {
+      // 解析输出获取剩余天数
+      const match = output.match(/剩余 (\d+) 天/);
+      if (match) {
+        const days = parseInt(match[1]);
+        resolve({ days, needsRenew: days <= 30 });
+      } else {
+        resolve({ days: 0, needsRenew: true });
+      }
+    });
+  });
+}
+
+// 定时任务
+setInterval(async () => {
+  const domains = ['example.com', 'api.example.com'];
+  
+  for (const domain of domains) {
+    const status = await checkCertExpiry(domain, `./certs/${domain}/${domain}.pem`);
+    
+    if (status.needsRenew) {
+      console.log(`证书 ${domain} 即将过期 (${status.days} 天)，开始续期...`);
+      await renewCertificate(domain);
+    }
+  }
+}, 24 * 60 * 60 * 1000); // 每天检查一次
+```
+
+---
+
+## 下一步
+
+1. **当前可用**：使用方式一（子进程调用）
+2. **未来规划**：如果需要真正的 Node.js SDK，可以开发 `certctl-sdk` 包
+3. **需求反馈**：如果有特定需求，请提交 Issue