{"_id":"@eazo/node-sdk","_rev":"2-38354438c8d74ddd019ce82eed69ad78","name":"@eazo/node-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@eazo/node-sdk","version":"0.1.0","keywords":["eazo","auth","decrypt","encryption","secp256k1","aes-256-gcm","ecc"],"author":{"name":"Eazo"},"license":"MIT","_id":"@eazo/node-sdk@0.1.0","maintainers":[{"name":"luozhuowei","email":"zhuowei@fellou.ai"},{"name":"liaochangjiang_fellou","email":"liaochangjiang@fellou.ai"}],"homepage":"https://github.com/EAZOAI/eazo-sdk#readme","bugs":{"url":"https://github.com/EAZOAI/eazo-sdk/issues"},"dist":{"shasum":"7e7f7afa5f7ddf448e6f6d500331479db669db7c","tarball":"https://registry.npmjs.org/@eazo/node-sdk/-/node-sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-YXVdhYKRCa4XfuF3NvZYAnfwqjidhaWKMMTko1XNCbqL1Cvd+tp6QG72bkFBZgudNc7c0HwizSJ4+R8OcQpMQQ==","signatures":[{"sig":"MEUCIQC3FHpxa1lIZYRO1dn4B94T0mRF1ZZxQ7K5zQjEzzNn/QIgcTa98hAcy3SyQ4IZWLcftp52bFcrp6hhLUIgPsjSunM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31257},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=14.0.0"},"gitHead":"24f56686ad732fb0fc47881b393fcec234a7f1c0","scripts":{"test":"node test/test.js","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"liaochangjiang_fellou","email":"liaochangjiang@fellou.ai"},"repository":{"url":"git+https://github.com/EAZOAI/eazo-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Eazo Node.js SDK - Decrypt encrypted data using ECC secp256k1 + AES-256-GCM","directories":{},"_nodeVersion":"20.20.0","dependencies":{"elliptic":"^6.6.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.11.0","@types/elliptic":"^6.4.18"},"_npmOperationalInternal":{"tmp":"tmp/node-sdk_0.1.0_1773386732840_0.5928546684709108","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-03-13T07:25:32.771Z","modified":"2026-06-02T11:59:51.813Z","0.1.0":"2026-03-13T07:25:32.988Z"},"bugs":{"url":"https://github.com/EAZOAI/eazo-sdk/issues"},"author":{"name":"Eazo"},"license":"MIT","homepage":"https://github.com/EAZOAI/eazo-sdk#readme","keywords":["eazo","auth","decrypt","encryption","secp256k1","aes-256-gcm","ecc"],"repository":{"url":"git+https://github.com/EAZOAI/eazo-sdk.git","type":"git"},"description":"Eazo Node.js SDK - Decrypt encrypted data using ECC secp256k1 + AES-256-GCM","maintainers":[{"email":"zhuowei@fellou.ai","name":"luozhuowei"},{"email":"liaochangjiang@fellou.ai","name":"liaochangjiang_fellou"},{"email":"suntianxiang@fellou.ai","name":"lucsun-fellou"}],"readme":"# @eazo/node-sdk\n\nEazo Node.js SDK - 使用 ECC secp256k1 + AES-256-GCM 混合加密解密数据。\n\n[![npm version](https://badge.fury.io/js/%40eazo%2Fnode-sdk.svg)](https://www.npmjs.com/package/@eazo/node-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 概述\n\n本 SDK 提供了一种简单、安全的方式来解密由 Eazo 平台加密的数据。它实现了**混合加密方案**（也称为\"数字信封\"），结合了：\n\n- **非对称加密（ECC secp256k1）**：用于加密对称密钥\n- **对称加密（AES-256-GCM）**：用于加密实际数据\n\n这种方案结合了 ECC 的安全性和 AES 的高效性，确保数据在传输过程中的安全。\n\n## 安装\n\n```bash\nnpm install @eazo/node-sdk\n```\n\n或使用 yarn:\n\n```bash\nyarn add @eazo/node-sdk\n```\n\n或使用 pnpm:\n\n```bash\npnpm add @eazo/node-sdk\n```\n\n## 快速开始\n\n### TypeScript / ES Modules\n\n```typescript\nimport { decrypt } from '@eazo/node-sdk';\n\nconst result = decrypt({\n  encryptedData: \"U2FsdGVkX1+ZqGx7J8kZ...\",\n  encryptedKey: \"BHRlc3RrZXkxMjM0NTY3ODkwYWJjZGVmZ2hpamtsbW5vcA==\",\n  iv: \"dGVzdGl2MTIzNDU2\",\n  authTag: \"dGVzdGF1dGh0YWc=\",\n  privateKey: \"c90fdaa22168c234c4c6628b80dc1cd129024e088a67cc74020bbea63b14e5c7\"\n});\n\nconsole.log(result.data); // 解析后的 JSON 对象或原始字符串\nconsole.log(result.raw);  // 原始解密字符串\n```\n\n### CommonJS\n\n```javascript\nconst { decrypt } = require('@eazo/node-sdk');\n\nconst result = decrypt({\n  encryptedData: \"...\",\n  encryptedKey: \"...\",\n  iv: \"...\",\n  authTag: \"...\",\n  privateKey: \"c90fdaa22168c234c4c6628b80dc1cd129024e088a67cc74020bbea63b14e5c7\"\n});\n\nconsole.log(result.data);\n```\n\n## 工作原理\n\n### 加密原理\n\nEazo 平台使用两阶段混合加密过程：\n\n```\n┌─────────────┐                    ┌─────────────┐\n│  平台服务器  │                    │   开发者     │\n└─────────────┘                    └─────────────┘\n       │                                  │\n       │  1. 生成随机 AES 密钥             │\n       │     (256 位)                     │\n       │                                  │\n       │  2. 用 AES-GCM 加密数据           │\n       │     → encryptedData              │\n       │                                  │\n       │  3. 用开发者公钥（ECC）加密 AES 密钥│\n       │     → encryptedKey               │\n       │                                  │\n       │  4. 发送加密数据包                │\n       │─────────────────────────────────>│\n       │                                  │\n       │                                  │  5. 用私钥解密 encryptedKey\n       │                                  │     → 得到 AES 密钥\n       │                                  │\n       │                                  │  6. 用 AES 密钥解密 encryptedData\n       │                                  │     → 得到原始数据\n```\n\n### 解密过程\n\n1. **提取临时公钥**：从加密密钥包中提取临时公钥\n2. **计算共享密钥**：使用 ECDH（椭圆曲线 Diffie-Hellman）算法\n3. **派生解密密钥**：通过 SHA-256 从共享密钥派生\n4. **解密 AES 密钥**：使用 AES-256-CBC 解密\n5. **解密实际数据**：使用解密得到的 AES 密钥和 AES-256-GCM 算法\n\n## API 参考\n\n### `decrypt(options)`\n\n解密使用 ECC secp256k1 + AES-256-GCM 混合加密的数据。\n\n#### 参数\n\n```typescript\ninterface DecryptOptions {\n  encryptedData: string;  // Base64 编码的加密数据\n  encryptedKey: string;   // Base64 编码的加密密钥\n  iv: string;             // Base64 编码的初始化向量\n  authTag: string;        // Base64 编码的认证标签\n  privateKey: string;     // 十六进制格式的私钥（64 字符）\n}\n```\n\n#### 返回值\n\n```typescript\ninterface DecryptResult<T = any> {\n  data: T;      // 解析后的 JSON 对象或原始字符串\n  raw: string;  // 原始解密字符串\n}\n```\n\n#### 异常\n\n- `Error` - 如果解密失败（无效密钥、数据损坏或缺少参数）\n\n### `decryptUserInfo(options)`\n\n用于解密 Eazo 平台用户信息的便捷函数。\n\n#### 返回值\n\n```typescript\ninterface UserInfo {\n  userId: string;\n  email?: string;\n  lang?: string;\n  region?: string;\n  nickname?: string;\n  avatarUrl?: string;\n  createdAt?: string;\n  [key: string]: any;\n}\n```\n\n## 使用示例\n\n### 示例 1：解密用户信息\n\n```typescript\nimport { decryptUserInfo } from '@eazo/node-sdk';\n\n// 从 Eazo 平台 API 获取加密数据\nconst response = await fetch('https://api.eazo.com/api/open/app-session-token', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer USER_TOKEN',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({ appId: 'your_app_id' })\n});\n\nconst { data } = await response.json();\n\n// 解密用户信息\nconst userInfo = decryptUserInfo({\n  encryptedData: data.encryptedData,\n  encryptedKey: data.encryptedKey,\n  iv: data.iv,\n  authTag: data.authTag,\n  privateKey: process.env.EAZO_PRIVATE_KEY! // 存储在环境变量中\n});\n\nconsole.log('用户 ID:', userInfo.userId);\nconsole.log('邮箱:', userInfo.email);\nconsole.log('昵称:', userInfo.nickname);\n```\n\n### 示例 2：解密通用数据\n\n```typescript\nimport { decrypt } from '@eazo/node-sdk';\n\n// 解密任何加密数据（不仅限于用户信息）\nconst result = decrypt({\n  encryptedData: \"...\",\n  encryptedKey: \"...\",\n  iv: \"...\",\n  authTag: \"...\",\n  privateKey: process.env.EAZO_PRIVATE_KEY!\n});\n\n// 访问解密后的数据\nif (typeof result.data === 'object') {\n  console.log('JSON 数据:', result.data);\n} else {\n  console.log('纯文本:', result.data);\n}\n\n// 访问原始字符串\nconsole.log('原始数据:', result.raw);\n```\n\n### 示例 3：错误处理\n\n```typescript\nimport { decrypt } from '@eazo/node-sdk';\n\ntry {\n  const result = decrypt({\n    encryptedData: data.encryptedData,\n    encryptedKey: data.encryptedKey,\n    iv: data.iv,\n    authTag: data.authTag,\n    privateKey: process.env.EAZO_PRIVATE_KEY!\n  });\n  \n  console.log('解密成功:', result.data);\n} catch (error) {\n  if (error instanceof Error) {\n    console.error('解密失败:', error.message);\n    \n    // 处理特定错误\n    if (error.message.includes('Invalid private key format')) {\n      console.error('请检查您的私钥格式');\n    } else if (error.message.includes('Missing required parameters')) {\n      console.error('缺少必需参数');\n    }\n  }\n}\n```\n\n### 示例 4：Express.js 集成\n\n```typescript\nimport express from 'express';\nimport { decryptUserInfo } from '@eazo/node-sdk';\n\nconst app = express();\napp.use(express.json());\n\napp.post('/api/user/verify', async (req, res) => {\n  try {\n    const { encryptedData, encryptedKey, iv, authTag } = req.body;\n    \n    // 解密用户信息\n    const userInfo = decryptUserInfo({\n      encryptedData,\n      encryptedKey,\n      iv,\n      authTag,\n      privateKey: process.env.EAZO_PRIVATE_KEY!\n    });\n    \n    // 验证并处理用户信息\n    res.json({\n      success: true,\n      userId: userInfo.userId,\n      email: userInfo.email\n    });\n  } catch (error) {\n    res.status(400).json({\n      success: false,\n      error: '解密失败'\n    });\n  }\n});\n\napp.listen(3000);\n```\n\n## 安全最佳实践\n\n### 1. 私钥管理\n\n✅ **推荐做法：**\n- 将私钥存储在环境变量中（如 `EAZO_PRIVATE_KEY`）\n- 使用密钥管理服务（AWS Secrets Manager、HashiCorp Vault）\n- 使用加密的配置文件，并限制文件权限\n\n❌ **避免做法：**\n- 在源代码中硬编码私钥\n- 将私钥提交到 Git 仓库\n- 在前端或客户端使用私钥\n\n### 2. 网络安全\n\n- 始终使用 HTTPS 传输数据\n- 验证 SSL 证书有效性\n- 实施 API 速率限制\n\n### 3. 数据处理\n\n- 在内存中处理解密后的数据，避免记录敏感信息\n- 实施最小权限原则\n- 使用后清除内存中的敏感数据\n\n### 4. 错误处理\n\n- 不要在错误消息中暴露私钥或解密细节\n- 记录解密失败事件用于审计\n- 实施重试机制应对网络问题\n\n## 密钥格式\n\n本 SDK 使用**十六进制格式**的私钥，比 RSA/PEM 格式更简洁：\n\n| 特性 | ECC secp256k1 (十六进制) | RSA 2048 (PEM) |\n|------|-------------------------|----------------|\n| 私钥长度 | 64 字符 | ~1700 字符 |\n| 公钥长度 | 66 字符（压缩） | ~400 字符 |\n| 安全级别 | 128 位 | 112 位 |\n| 速度 | 快 | 慢 |\n| 存储空间 | 小 | 大 |\n\n示例私钥格式：\n```\nc90fdaa22168c234c4c6628b80dc1cd129024e088a67cc74020bbea63b14e5c7\n```\n\n## 系统要求\n\n- Node.js >= 14.0.0\n- TypeScript >= 5.0.0（用于 TypeScript 项目）\n\n## 依赖\n\n- `elliptic`：用于 secp256k1 的 ECC 加密库\n- 内置 `crypto` 模块：用于 AES 加密/解密\n\n## 故障排除\n\n### 解密失败：\"Invalid private key format\"\n\n**解决方案：** 确保您的私钥是十六进制格式（64 字符），没有任何前缀或后缀。\n\n```typescript\n// ✅ 正确\nconst privateKey = \"c90fdaa22168c234c4c6628b80dc1cd129024e088a67cc74020bbea63b14e5c7\";\n\n// ❌ 错误\nconst privateKey = \"0xc90fdaa...\"; // 不要 0x 前缀\nconst privateKey = \"c90f...==\";    // 不是 base64\n```\n\n### 解密失败：\"Unsupported state or unable to authenticate data\"\n\n**解决方案：** 这通常意味着：\n- 加密数据已被篡改\n- 使用了错误的私钥\n- 传输过程中数据损坏\n\n验证您使用的是正确的私钥，且数据未被修改。\n\n### 模块导入错误\n\n**解决方案：** 检查您的模块系统：\n\n```javascript\n// CommonJS\nconst { decrypt } = require('@eazo/node-sdk');\n\n// ES Modules\nimport { decrypt } from '@eazo/node-sdk';\n```\n\n## 许可证\n\nMIT\n\n## 技术支持\n\n- GitHub Issues: [https://github.com/your-org/eazo-sdk/issues](https://github.com/your-org/eazo-sdk/issues)\n- 文档: [https://docs.eazo.com](https://docs.eazo.com)\n- 邮箱: developer-support@eazo.com\n\n## 贡献\n\n欢迎贡献！提交 Pull Request 前请阅读我们的贡献指南。\n\n---\n\n**最后更新**: 2024-03-13  \n**SDK 版本**: 1.0.0\n","readmeFilename":"README.zh-CN.md"}