跳轉到主要內容
ChainStream 採用多層安全機制保護 API 訪問。本文件介紹 API 安全最佳實踐、常見威脅防護及安全配置指南。
最後更新: 2026 年 2 月 | 版本: v2.0

認證安全

Access Token 機制

ChainStream 使用基於 OAuth 2.0 的認證機制,透過 Client ID 和 Client Secret 生成 JWT Access Token 進行 API 認證。 認證流程: 憑據規範
專案規範
Client ID應用唯一識別符號
Client Secret64 位隨機字元
Access TokenJWT 格式,包含過期時間和許可權範圍
Token 有效期24 小時

Access Token 獲取

import { AuthenticationClient } from 'auth0';

const auth0Client = new AuthenticationClient({
  domain: 'dex.asia.auth.chainstream.io',
  clientId: process.env.CHAINSTREAM_CLIENT_ID,
  clientSecret: process.env.CHAINSTREAM_CLIENT_SECRET
});

const { data } = await auth0Client.oauth.clientCredentialsGrant({
  audience: 'https://api.dex.chainstream.io'
});

const accessToken = data.access_token;

憑據安全

儲存要求
Client Secret 是訪問 ChainStream 服務的核心憑證,洩露可能導致服務濫用和費用損失。
儲存方式安全等級說明
環境變數✅ 推薦不進入版本控制
金鑰管理服務✅ 最佳AWS Secrets Manager, HashiCorp Vault 等
配置檔案⚠️ 注意必須加入 .gitignore
程式碼硬編碼❌ 禁止極易洩露

程式碼示例

// ❌ 危险:硬编码凭据
const clientId = "your_client_id";
const clientSecret = "your_secret";

// ❌ 危险:提交到版本控制
// config.json: { "client_id": "...", "client_secret": "..." }

// ✅ 安全:使用环境变量
const clientId = process.env.CHAINSTREAM_CLIENT_ID;
const clientSecret = process.env.CHAINSTREAM_CLIENT_SECRET;

// ✅ 安全:使用密钥管理服务
const credentials = await secretsManager.getSecret('chainstream-credentials');

多 App 管理

建議為不同環境和服務建立獨立的 App:
用途App 名稱建議說明
生產環境prod-main生產業務使用
測試環境test-dev開發測試使用
CI/CDci-pipeline自動化測試使用
監控服務monitoring監控告警使用

傳輸安全

TLS 要求

專案要求
最低版本TLS 1.2
推薦版本TLS 1.3
證書驗證必須啟用
不支援HTTP、TLS 1.0/1.1

證書驗證

生產環境中絕不跳過證書驗證,這會使您的應用暴露於中間人攻擊風險。
// ❌ 危险:跳过证书验证
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

// ✅ 安全:正常证书验证(默认行为)
const response = await fetch('https://api.chainstream.io/v1/...');

Webhook 安全

Webhook 訊息透過簽名機制確保訊息來源的可靠性。

簽名驗證

當您收到 Webhook 訊息時,需要使用 Webhook Secret 驗證簽名,確認訊息來自 ChainStream 且未被篡改。
專案說明
演算法HMAC-SHA256
金鑰Webhook Secret(在 Dashboard 配置)
簽名頭X-Webhook-Signature

驗證示例

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express 中间件示例
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // 处理 webhook 消息
  console.log('Received webhook:', req.body);
  res.status(200).send('OK');
});

Webhook Secret 輪換

如需輪換 Webhook Secret:
1

生成新 Secret

Dashboard → Webhooks → 選擇 Endpoint → 輪換 Secret
2

更新應用配置

在應用中更新為新的 Webhook Secret
3

驗證簽名

確認新 Secret 可以正確驗證簽名

使用量監控

Metrics 面板

在 Dashboard 的 Metrics 面板中,可以檢視 API 和 WebSocket 的呼叫情況:
指標說明
請求 IP請求來源 IP 地址
User Agent請求的客戶端標識
響應碼HTTP 狀態碼
耗時請求響應時間
消耗 Units本次請求消耗的用量單位
總計用量累計消耗的用量

圖表資料

Metrics 面板提供多種時間維度的圖表:
  • 小時維度 — 檢視最近 24 小時的呼叫趨勢
  • 天維度 — 檢視最近 30 天的呼叫趨勢
  • 月維度 — 檢視歷史月度統計
檢視路徑: Dashboard → Metrics

安全監控

🚧 Coming Soon — 安全監控功能正在開發中,即將上線。
上線後將支援:
  • 異常檢測 — 自動檢測認證失敗激增、異常地理位置等
  • 告警通知 — 郵件和 Webhook 告警
  • 自動防護 — 臨時封禁、請求限流等

IP 白名單

🚧 Coming Soon — IP 白名單功能正在開發中,即將上線。
上線後將支援:
  • 單個 IP 配置(如 203.0.113.50
  • IP 段配置(如 203.0.113.0/24
  • 多 IP 配置(逗號分隔)

常見攻擊防護

中間人攻擊

攻擊方式: 攻擊者在客戶端和伺服器之間攔截通訊。 防護措施:
措施說明
強制 HTTPS僅支援 TLS 1.2+
證書驗證必須啟用證書驗證
HSTS強制 HTTPS 連線

注入攻擊

攻擊方式: 攻擊者透過輸入惡意資料嘗試執行未授權操作。 防護措施:
措施說明
輸入驗證嚴格的引數型別檢查
引數化查詢防止 SQL/NoSQL 注入
輸出編碼防止 XSS

憑據洩露響應

如果懷疑 Client Secret 已洩露,請立即執行以下步驟:
1

立即刪除 App

Dashboard → Apps → 選擇 App → 刪除
2

建立新 App

Dashboard → Apps → 建立新 App
3

更新應用配置

在所有使用該憑據的應用中更新為新 Client ID 和 Secret
4

檢查 Metrics

Dashboard → Metrics → 檢查是否有異常呼叫
5

審查安全實踐

檢查憑據洩露原因,改進安全措施

安全錯誤碼

認證相關

錯誤碼HTTP 狀態說明
UNAUTHORIZED401未提供認證資訊
EXPIRED_TOKEN401Access Token 已過期
INVALID_TOKEN401Access Token 無效
INVALID_CREDENTIALS401Client ID 或 Secret 錯誤

訪問控制相關

錯誤碼HTTP 狀態說明
FORBIDDEN403無許可權訪問或用量不足
RATE_LIMITED429請求頻率超限
INSUFFICIENT_SCOPE403Token 許可權不足

Webhook 相關

錯誤碼說明
INVALID_SIGNATUREWebhook 簽名驗證失敗
MISSING_SIGNATURE缺少簽名頭

錯誤響應示例

{
  "error": {
    "code": "EXPIRED_TOKEN",
    "message": "Access token has expired",
    "details": {
      "expired_at": "2024-01-15T10:30:00Z"
    }
  }
}

安全配置清單

基礎配置(必須)

  • 使用 HTTPS 訪問 API
  • Client ID 和 Client Secret 儲存在環境變數或金鑰管理服務
  • 不在程式碼倉庫中提交憑據
  • 生產/測試環境使用不同 App
  • 正確驗證 Webhook 簽名

進階配置(推薦)

  • 整合金鑰管理服務(AWS Secrets Manager / HashiCorp Vault)
  • 定期檢查 Metrics 面板的呼叫情況
  • 為不同服務建立獨立的 App

企業配置(可選)

  • 整合 SIEM 系統進行日誌分析
  • 制定安全事件響應流程

常見問題

立即登入 Dashboard 刪除該 App,建立新 App,然後更新所有使用該憑據的應用配置。詳見上方”憑據洩露響應”章節。
Access Token 有效期為 24 小時。建議:
  1. 快取 Token — 在有效期內複用同一個 Token
  2. 提前重新整理 — 在過期前 1 小時左右重新整理 Token
  3. 錯誤重試 — 收到 401 錯誤時自動獲取新 Token
登入 Dashboard → Metrics,可以檢視請求 IP、響應碼、耗時、消耗的 Units 等資訊,以及時間維度的圖表資料。
常見原因:
  1. Secret 不匹配 — 確認使用正確的 Webhook Secret
  2. Payload 處理錯誤 — 確保使用原始的 JSON 字串進行簽名計算
  3. 簽名頭缺失 — 確認請求頭中包含 X-Webhook-Signature
支援。建議為不同環境(生產/測試)和不同服務建立獨立的 App,便於管理和問題排查。

相關文件

認證

認證與憑據管理

資料隱私

資料隱私政策

錯誤碼

完整錯誤碼列表

Webhook 基礎

Webhook 配置與使用