channel-key-derivation — CKD JS SDK

CKD（Channel Key Derivation）的 JavaScript SDK。

对应 Go 版本：github.com/doc-war/ckd
对应 Rust 版本：github.com/doc-war/ckd-rust

概述

CKD（Channel Key Derivation）是一种轻量级、无状态、可逆的资源标识派生协议。

它允许从一个内部资源标识派生出多个不同用途的外部标识，并支持在不依赖映射表的情况下恢复原始资源标识。

目标

CKD 的核心目标：

• 一个内部资源 ID
• 派生多个用途隔离的外部 Key
• 无数据库映射
• 可逆恢复
• 不同用途之间不可互相推导

在数学上的具体表现为：

• C → A
• C → B
• A → C
• B → C
• A 无法推导 B
• B 无法推导 A
• 不需要存储 A→C 映射
• 不需要存储 B→C 映射
• 仅依赖平台密钥即可完成派生和反向解析
• 且无法使用已知的AB来反向破解密钥

价值

采用CKD的O(1)复杂度，相比库索引，在数值上的影响是直观的：

| 指标 | 查库 | CKD | | ------------ | -------- | ---------- | | 单次路由延迟 | 1~10ms | 0.01~0.1ms | | 单机QPS | 1万~5万 | 10万~50万 | | 横向扩容 | 受DB限制 | 近线性 | | Redis依赖 | 需要 | 不需要 | | MySQL依赖 | 需要 | 不需要 |

对于极纯粹的高并发技术设施，将系统从“状态驱动路由”变成“计算驱动路由”，减少两次查库，并发能力提升通常不是 2 倍、3 倍，而是一个数量级（10x）起步。

安装

npm install channel-key-derivation

快速开始

import { CKD } from 'channel-key-derivation';

const secret = Buffer.from([
  0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
  0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
  0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
  0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
]);

const ckd = new CKD({
  currentVersion: 1,
  secretsByVersion: { 1: secret },
});

const channelId = Buffer.from('channel_12345');
const webhookKey = await ckd.derive(channelId, 'webhook');
const sseKey = await ckd.derive(channelId, 'sse');

const recovered = await ckd.parse(webhookKey, 'webhook');
console.log(recovered.toString()); // 'channel_12345'

API

new CKD(config)

| 参数 | 类型 | 说明 | |------|------|------| | config.currentVersion | number | 当前生效的密钥版本号 [1, 15] | | config.secretsByVersion | object | 多版本密钥映射表 { 1: secretBuffer } |

async ckd.derive(resourceId, purpose)

| 参数 | 类型 | 说明 | |------|------|------| | resourceId | Uint8Array | 内部资源标识 | | purpose | string | 用途标识 [a-z0-9_-]{1,64} |

返回 Promise<string> base64url 编码的派生密钥。

async ckd.parse(derivedKey, purpose)

| 参数 | 类型 | 说明 | |------|------|------| | derivedKey | string | base64url 编码的派生密钥 | | purpose | string | 用途标识 |

返回 Promise<Buffer> 原始资源 ID。

错误处理

import { CkdError, ErrInvalidPurpose, ErrInvalidDerivedKey } from 'channel-key-derivation';

try {
  await ckd.parse('!!!', 'webhook');
} catch (err) {
  if (err === ErrInvalidDerivedKey) {
    // 格式错误 / 认证失败 / 版本不存在
  }
}

密钥轮换

const ckd = new CKD({
  currentVersion: 2,
  secretsByVersion: {
    1: oldSecret,  // 保留，用于解析旧 Key
    2: newSecret,  // 新派生使用此密钥
  },
});

const newKey = await ckd.derive(channelId, 'webhook'); // 使用 v2
const recovered = await ckd.parse(oldKey, 'webhook');  // v1 仍可解析

跨语言测试向量

| # | Secret | Purpose | Ver | ResourceID | K | |---|--------|---------|-----|------------|---| | 1 | 0001...1e1f (32B) | webhook | 1 | channel_12345 | AXnjdNQal5XDP66STw0pQbOzRi3AdGmiX1Xi5ZxO | | 2 | 0001...1e1f (32B) | sse | 1 | user_67890 | Aez5p0zdhSjxmsgy92MfMhiMlhAbRxlldWcl | | 3 | ffee...1100 (32B) | api_token | 2 | channel_12345 | ApUFLCCTYol1B57b459DrXW8SiQaJLaJRUx246YY |

Go、Rust、JS 三端产出完全一致。

测试

npm test

许可

MIT