@steve02081504/fount-p2p 0.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @steve02081504/fount-p2p
+
+fount federation P2P layer: node identity, link handshake, TrustGraph, Mailbox store-and-forward, DAG timeline, EVFS entity files.
+
+## Used by
+
+- [fount](https://github.com/steve02081504/fount)
+- [subfount](https://github.com/steve02081504/subfount)
+
+## Install
+
+```bash
+npm install @steve02081504/fount-p2p
+```
+
+Requires **Node.js ≥ 20** (ESM + `import ... with { type: 'json' }`).
+
+## Quick start
+
+```javascript
+import { startNode, createScopedLinkRoom, ensureUserRoom } from '@steve02081504/fount-p2p'
+
+await startNode({ nodeDir: '/path/to/p2p/node' })
+await ensureUserRoom()
+```
+
+Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`, `@steve02081504/fount-p2p/transport/link_registry`, `@steve02081504/fount-p2p/registries/event_type`.
+
+## Layout
+
+| Layer | Directory | Role |
+|---|---|---|
+| L0 | `core/` | Pure primitives: `hexIds`, `entity_id*`, `canonical_json` |
+| L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
+| L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
+| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery, RTC links, rooms |
+| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `entity/` | Federation, store-and-forward, DAG, EVFS |
+| — | `registries/` | Pluggable registries (event type, part path, room provider, …) |
+
+Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscoveryProvider`, …).
+
+Root contains only the facade and package metadata; all modules live in layered subdirectories. After a layout migration, run `node scripts/cleanup-root-duplicates.mjs` to drop stale root stubs.
+
+## Tests
+
+```bash
+npm test              # pure + integration (--test-force-exit: node-datachannel leaves native handles)
+npm run test:live     # RTC / link smoke (requires node-datachannel)
+npm run test:sim      # tunables co-evolution sim (dev only, not published; --social-tunables to write back)
+```
+
+During development: `node scripts/check-imports.mjs` validates relative imports. After a layout migration, `node scripts/cleanup-root-duplicates.mjs` removes stale root-level stubs.
+
+## Optional dependencies
+
+- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth discovery (attempted by default; skipped when not installed)
+
+Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStoragePlugin` and injected; see `node/storage_plugins.mjs` for the local reference implementation.
+
+## Docs
+
+- Signaling and link setup: [`docs/signaling.md`](./docs/signaling.md)

package/core/bytes_codec.mjs

@@ -0,0 +1,51 @@
+/**
+ * Base64 / hex / bytes 互转（无 Node 依赖，浏览器与 Node 共用）。
+ */
+
+/**
+ * @param {ArrayBuffer} buffer 原始二进制缓冲
+ * @returns {string} 标准 Base64 文本
+ */
+export function arrayBufferToBase64(buffer) {
+	let binary = ''
+	const bytes = new Uint8Array(buffer)
+	for (let index = 0; index < bytes.byteLength; index++)
+		binary += String.fromCharCode(bytes[index])
+	return btoa(binary)
+}
+
+/**
+ * @param {Uint8Array} u8 原始字节
+ * @returns {string} 标准 Base64 文本
+ */
+export function u8ToB64(u8) {
+	let binary = ''
+	for (let index = 0; index < u8.length; index++) binary += String.fromCharCode(u8[index])
+	return btoa(binary)
+}
+
+/**
+ * @param {string} b64 标准 Base64 文本
+ * @returns {Uint8Array} 解码后的字节
+ */
+export function b64ToU8(b64) {
+	const bin = atob(b64)
+	const out = new Uint8Array(bin.length)
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+	return out
+}
+
+/**
+ * @param {string} hex 十六进制文本（可带 0x 前缀，长度须为 2×nBytes）
+ * @param {number} nBytes 目标字节数
+ * @returns {Uint8Array} 解析得到的字节数组
+ */
+export function hexToNBytes(hex, nBytes) {
+	const normalizedHex = String(hex).replace(/^0x/iu, '').trim()
+	if (normalizedHex.length !== nBytes * 2 || !/^[\da-f]+$/iu.test(normalizedHex))
+		throw new RangeError('invalid hex length or characters')
+	const out = new Uint8Array(nBytes)
+	for (let index = 0; index < nBytes; index++)
+		out[index] = parseInt(normalizedHex.slice(index * 2, index * 2 + 2), 16)
+	return out
+}

package/core/canonical_json.mjs

@@ -0,0 +1,21 @@
+/**
+ * 确定性 JSON 序列化（键排序），用于 event id 与验签负载
+ *
+ * @param {unknown} value 任意可 JSON 化的结构（禁止 BigInt）
+ * @returns {string} 键已排序的紧凑 JSON 文本
+ */
+export function canonicalStringify(value) {
+	if (value === null || value === undefined) return JSON.stringify(value)
+	if (typeof value === 'bigint') throw new TypeError('BigInt not allowed in canonical JSON')
+	if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'string')
+		return JSON.stringify(value)
+	if (Array.isArray(value))
+		return `[${value.map(item => item === undefined ? 'null' : canonicalStringify(item)).join(',')}]`
+	if (typeof value === 'object') {
+		// 跳过值为 undefined 的键，与 JSON.stringify 语义一致：否则 canonical 串会写出字面量 `undefined`，
+		// 而事件经 JSON wire/落盘往返后这些键会消失，导致 computeEventId 两端不一致（id_mismatch）。
+		const keys = Object.keys(value).filter(k => value[k] !== undefined).sort()
+		return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(value[k])}`).join(',')}}`
+	}
+	throw new TypeError(`Unsupported type: ${typeof value}`)
+}

package/core/composite_key.mjs

@@ -0,0 +1,91 @@
+/** 进程内 Map 复合键（`\0` 分隔；V8 对短 ConsString 拼接很快）。 */
+
+const SEP = '\0'
+
+/**
+ * @param {...string} parts 键段（至少一段）
+ * @returns {string} 复合键
+ */
+export function compositeKey(...parts) {
+	if (!parts.length) throw new Error('compositeKey: at least one part required')
+	return parts.join(SEP)
+}
+
+/**
+ * @param {...string} prefixParts 前缀段（可为空，表示整表）
+ * @returns {string} 带尾部分隔符的前缀（用于子树匹配）
+ */
+function compositePrefix(...prefixParts) {
+	return prefixParts.length ? `${compositeKey(...prefixParts)}${SEP}` : ''
+}
+
+/**
+ * @template V
+ * @param {Map<string, V>} map 根表
+ * @param {...string} parts 键段
+ * @returns {V | undefined} 命中值
+ */
+export function mapGet(map, ...parts) {
+	return map.get(compositeKey(...parts))
+}
+
+/**
+ * @template V
+ * @param {Map<string, V>} map 根表
+ * @param {...string} partsAndValue 键段 + 末尾值
+ * @returns {void}
+ */
+export function mapSet(map, ...partsAndValue) {
+	const value = partsAndValue.pop()
+	map.set(compositeKey(...partsAndValue), value)
+}
+
+/**
+ * @template V
+ * @param {Map<string, V>} map 根表
+ * @param {...string} parts 键段
+ * @returns {boolean} 是否存在
+ */
+export function mapHas(map, ...parts) {
+	return map.has(compositeKey(...parts))
+}
+
+/**
+ * @template V
+ * @param {Map<string, V>} map 根表
+ * @param {...string} parts 键段
+ * @returns {void}
+ */
+export function mapDelete(map, ...parts) {
+	map.delete(compositeKey(...parts))
+}
+
+/**
+ * 删除以 `prefixParts` 为前缀的所有条目（含更深层级）。
+ * @template V
+ * @param {Map<string, V>} map 根表
+ * @param {...string} prefixParts 前缀段（空则清空整表）
+ * @returns {void}
+ */
+export function mapDeleteByPrefix(map, ...prefixParts) {
+	const prefix = compositePrefix(...prefixParts)
+	for (const k of [...map.keys()])
+		if (!prefix || k.startsWith(prefix)) map.delete(k)
+}
+
+/**
+ * 遍历前缀子树；回调收到前缀之后的各段与值。
+ * @template V
+ * @param {Map<string, V>} map 根表
+ * @param {...(string | ((tail: string[], value: V) => void))} prefixPartsAndFn 前缀段 + 末尾回调
+ * @returns {void}
+ */
+export function mapForEachUnder(map, ...prefixPartsAndFn) {
+	const fn = prefixPartsAndFn.pop()
+	const prefix = compositePrefix(...prefixPartsAndFn)
+	for (const [k, value] of map) {
+		if (!k.startsWith(prefix)) continue
+		const tail = k.slice(prefix.length).split(SEP).filter(Boolean)
+		fn(tail, value)
+	}
+}

package/core/constants.mjs

@@ -0,0 +1,53 @@
+import { resolveFederationFanoutTopK } from '../trust_graph/resolve.mjs'
+import trustGraphTunables from '../trust_graph/tunables.json' with { type: 'json' }
+
+/** @type {readonly string[]} 权限键注册表顺序（运算期 BigInt 编码用） */
+export const PERMISSION_REGISTRY_ORDER = Object.freeze([
+	'VIEW_CHANNEL',
+	'SEND_MESSAGES',
+	'SEND_STICKERS',
+	'ADD_REACTIONS',
+	'MANAGE_MESSAGES',
+	'MANAGE_CHANNELS',
+	'KICK_MEMBERS',
+	'BAN_MEMBERS',
+	'MANAGE_ROLES',
+	'MANAGE_ADMINS',
+	'INVITE_MEMBERS',
+	'STREAM',
+	'CREATE_THREADS',
+	'UPLOAD_FILES',
+	'MANAGE_FILES',
+	'PIN_MESSAGES',
+	'SET_WORLD',
+	'ADMIN',
+	'BYPASS_RATE_LIMIT',
+])
+
+/**
+ * 默认晚消息冻结时间（毫秒）
+ */
+export const DEFAULT_LATE_MESSAGE_FREEZE_MS = 30_000
+/**
+ * 占位 `message` 无 `message_edit` 终稿时的空闲截断（毫秒）；§6.4 `streamGeneratingIdleMs` 默认。
+ */
+export const DEFAULT_STREAM_GENERATING_IDLE_MS = 150_000
+/**
+ * 默认最大捕获事件数
+ */
+export const DEFAULT_MAX_CATCHUP_EVENTS = 50_000
+/**
+ * 成员页面大小
+ */
+export const MEMBERS_PAGE_SIZE = 500
+/** Checkpoint 中保留的 epoch 链历史条数上限 */
+export const EPOCH_CHAIN_MAX = 256
+
+/** 群文件经联邦复制的单块上限（字节，§10.2） */
+export const FEDERATION_CHUNK_MAX_BYTES = trustGraphTunables.federationChunkMaxBytes
+
+/** TrustGraph fanout 参考 Top-K（N=8 roster 时的缩放值；运行时请用 resolveFederationFanoutTopK） */
+export const FEDERATION_FANOUT_TOP_K = resolveFederationFanoutTopK(8, trustGraphTunables)
+
+/** 全局 fed_chunk_get miss 时 fanout 邻居数 */
+export const FEDERATION_CHUNK_FETCH_FANOUT_K = trustGraphTunables.federationChunkFetchFanoutK

package/core/entity_id.mjs

@@ -0,0 +1,53 @@
+import { Buffer } from 'node:buffer'
+
+import { pubKeyHash } from '../crypto/crypto.mjs'
+
+import {
+	encodeEntityHash,
+	ENTITY_HASH_RE,
+	isEntityHash128,
+	parseEntityHash,
+} from './entity_id_parse.mjs'
+import { isHex64, normalizeHex64 } from './hexIds.mjs'
+
+/**
+ *
+ */
+export {
+	encodeEntityHash,
+	ENTITY_HASH_RE,
+	isEntityHash128,
+	parseEntityHash,
+}
+
+/**
+ * @param {unknown} pubKeyHex 32 字节公钥 hex
+ * @returns {string} 64 位 nodeHash / subjectHash（pubKeyHash）
+ */
+export function hashFromPubKeyHex(pubKeyHex) {
+	const hex = normalizeHex64(pubKeyHex)
+	if (!isHex64(hex) || Buffer.from(hex, 'hex').length !== 32)
+		throw new Error('invalid pubKeyHex')
+	return pubKeyHash(Buffer.from(hex, 'hex'))
+}
+
+/**
+ * @param {string} nodeHash 成员所属节点 hash
+ * @param {string} recoveryPubKeyHex 32 字节 recovery 公钥 hex（稳定身份锚）
+ * @returns {string} 用户 entityHash
+ */
+export function userEntityHashFromRecoveryPubKeyHex(nodeHash, recoveryPubKeyHex) {
+	return encodeEntityHash(nodeHash, hashFromPubKeyHex(recoveryPubKeyHex))
+}
+
+/**
+ * @param {string} nodeHash 成员所属节点 hash
+ * @param {string} subjectHash 成员签名 pubKeyHash（DAG sender）
+ * @returns {string} 用户 entityHash
+ */
+export function userEntityHashFromSubjectHash(nodeHash, subjectHash) {
+	const node = normalizeHex64(nodeHash)
+	const subject = normalizeHex64(subjectHash)
+	if (!isHex64(node) || !isHex64(subject)) throw new Error('invalid subject hash')
+	return encodeEntityHash(node, subject)
+}

package/core/entity_id_parse.mjs

@@ -0,0 +1,40 @@
+import { isHex64, normalizeHex64 } from './hexIds.mjs'
+
+/** 128 位小写 hex：`nodeHash(64)` + `subjectHash(64)`。 */
+export const ENTITY_HASH_RE = /^[\da-f]{128}$/u
+
+/**
+ * @param {unknown} value 待校验值
+ * @returns {boolean} 是否为合法 128 位 hex
+ */
+export function isEntityHash128(value) {
+	const raw = String(value ?? '').trim().toLowerCase().replace(/^0x/iu, '')
+	return ENTITY_HASH_RE.test(raw)
+}
+
+/**
+ * @param {unknown} entityHash 128 位 entityHash
+ * @returns {{ entityHash: string, nodeHash: string, subjectHash: string } | null} 解析结果；非法时 null
+ */
+export function parseEntityHash(entityHash) {
+	const raw = String(entityHash ?? '').trim().toLowerCase().replace(/^0x/iu, '')
+	if (!ENTITY_HASH_RE.test(raw)) return null
+	return {
+		entityHash: raw,
+		nodeHash: raw.slice(0, 64),
+		subjectHash: raw.slice(64, 128),
+	}
+}
+
+/**
+ * @param {string} nodeHash 所属节点（64 hex）
+ * @param {string} subjectHash 主体 hash（64 hex）
+ * @returns {string} 128 位 entityHash
+ */
+export function encodeEntityHash(nodeHash, subjectHash) {
+	const node = normalizeHex64(nodeHash)
+	const subject = normalizeHex64(subjectHash)
+	if (!isHex64(node) || !isHex64(subject))
+		throw new Error('invalid entity hash parts')
+	return node + subject
+}

package/core/evfs_logical_path.mjs

@@ -0,0 +1,15 @@
+/**
+ * @param {string} logicalPath EVFS 逻辑路径
+ * @returns {string} 规范化后的相对路径
+ */
+export function assertSafeEvfsLogicalPath(logicalPath) {
+	const raw = String(logicalPath || '').trim()
+	if (!raw || raw.includes('\0'))
+		throw new Error('invalid EVFS path')
+	const segments = raw.split(/[/\\]+/).map(s => s.trim()).filter(Boolean)
+	if (!segments.length) throw new Error('invalid EVFS path')
+	for (const segment of segments)
+		if (segment === '.' || segment === '..')
+			throw new Error('invalid EVFS path traversal')
+	return segments.join('/')
+}

package/core/hexIds.mjs

@@ -0,0 +1,73 @@
+/** 64 位小写十六进制（DAG 事件 id、公钥哈希等）。 */
+export const HEX_ID_64 = /^[\da-f]{64}$/u
+
+/** 签名 hex（128 字符）。 */
+export const SIGNATURE_HEX_128 = /^[\da-f]{128}$/u
+
+/** `blob:<64hex>` 存储定位符。 */
+export const BLOB_STORAGE_LOCATOR_RE = /^blob:([\da-f]{64})$/u
+
+/** `local:…/chunks/<64hex>.bin` 群分块路径。 */
+export const LOCAL_CHUNK_FILE_RE = /^local:[^/]+\/chunks\/([\da-f]{64})\.bin$/u
+
+/**
+ * @param {unknown} value 原始字符串
+ * @returns {string} trim + 去 0x + 小写
+ */
+export function normalizeHex64(value) {
+	return String(value ?? '').trim().toLowerCase().replace(/^0x/iu, '')
+}
+
+/**
+ * @param {unknown} value 待校验值
+ * @returns {boolean} 是否为 64 位 hex
+ */
+export function isHex64(value) {
+	return HEX_ID_64.test(normalizeHex64(value))
+}
+
+/**
+ * 64 位 hex eventId 字典序比较（固定宽度 ASCII，不用 localeCompare）。
+ * @param {unknown} a 左操作数
+ * @param {unknown} b 右操作数
+ * @returns {number} 排序比较结果
+ */
+export function compareHex64Asc(a, b) {
+	const sa = normalizeHex64(a)
+	const sb = normalizeHex64(b)
+	return sa < sb ? -1 : sa > sb ? 1 : 0
+}
+
+/**
+ * 外部入站专用：规范化并断言 64 位 hex。
+ * @param {unknown} value 原始值
+ * @param {string} [label='hex64'] 字段名（错误信息）
+ * @returns {string} 小写 64 位 hex
+ */
+export function assertHex64(value, label = 'hex64') {
+	const normalized = normalizeHex64(value)
+	if (!HEX_ID_64.test(normalized))
+		throw new Error(`${label} must be 64 hex characters`)
+	return normalized
+}
+
+/**
+ * @param {unknown} value 待校验值
+ * @returns {boolean} 是否为 128 位签名 hex
+ */
+export function isSignatureHex128(value) {
+	return SIGNATURE_HEX_128.test(String(value ?? '').trim())
+}
+
+/**
+ * 外部入站专用：断言 128 位签名 hex。
+ * @param {unknown} value 原始值
+ * @param {string} [label='signature'] 字段名
+ * @returns {string} 签名 hex
+ */
+export function assertSignatureHex128(value, label = 'signature') {
+	const normalized = String(value ?? '').trim().toLowerCase()
+	if (!SIGNATURE_HEX_128.test(normalized))
+		throw new Error(`${label} must be 128 hex characters`)
+	return normalized
+}

package/core/hlc.mjs

@@ -0,0 +1,114 @@
+/**
+ * 混合逻辑时钟 (Hybrid Logical Clock)
+ * 用于分布式系统中的事件排序
+ */
+
+/**
+ * 混合逻辑时钟实例：由物理 wall 与 logical 计数组成。
+ */
+export class HLC {
+	/**
+	 * @param {number} [wall=0] - 物理时间戳（毫秒）
+	 * @param {number} [logical=0] - 逻辑计数（同 wall 下递增）
+	 */
+	constructor(wall = 0, logical = 0) {
+		this.wall = wall
+		this.logical = logical
+	}
+
+	/**
+	 * 创建当前时间的 HLC
+	 * @returns {HLC} wall 为当前时间、logical 为 0 的实例
+	 */
+	static now() {
+		return new HLC(Date.now(), 0)
+	}
+
+	/**
+	 * 更新 HLC（接收到远程事件时）
+	 * @param {HLC} remote - 远程 HLC
+	 * @returns {HLC} 合并规则后的新 HLC 实例
+	 */
+	update(remote) {
+		const localWall = Date.now()
+
+		if (localWall > this.wall && localWall > remote.wall)
+			return new HLC(localWall, 0)
+
+
+		if (this.wall === remote.wall)
+			return new HLC(this.wall, Math.max(this.logical, remote.logical) + 1)
+
+
+		if (this.wall > remote.wall)
+			return new HLC(this.wall, this.logical + 1)
+
+
+		return new HLC(remote.wall, remote.logical + 1)
+	}
+
+	/**
+	 * 递增 HLC（本地生成新事件时）
+	 * @returns {HLC} tick 后的新实例
+	 */
+	tick() {
+		const localWall = Date.now()
+
+		if (localWall > this.wall)
+			return new HLC(localWall, 0)
+
+
+		return new HLC(this.wall, this.logical + 1)
+	}
+
+	/**
+	 * 比较两个 HLC
+	 * @param {HLC} other - 另一个 HLC
+	 * @returns {number} 小于零、零或大于零（与 `this - other` 同号）
+	 */
+	compare(other) {
+		if (this.wall !== other.wall)
+			return this.wall - other.wall
+
+		return this.logical - other.logical
+	}
+
+	/**
+	 * 转换为 JSON
+	 * @returns {{ wall: number, logical: number }} 可序列化的纯对象
+	 */
+	toJSON() {
+		return {
+			wall: this.wall,
+			logical: this.logical
+		}
+	}
+
+	/**
+	 * 从 JSON 创建 HLC
+	 * @param {{ wall: number, logical: number }} json - JSON 对象
+	 * @returns {HLC} 恢复的 HLC 实例
+	 */
+	static fromJSON(json) {
+		return new HLC(json.wall, json.logical)
+	}
+}
+
+/**
+ * 生成新事件的 HLC：取上一个事件的 HLC 与当前墙上时间的合并结果（`update`），
+ * 保证新 HLC 严格晚于 lastHlc（Lamport 单调性）且不早于 `wallMs`。
+ *
+ * @param {{ wall: number, logical: number } | null | undefined} lastHlcJson 上一事件的 HLC（来自已持久化事件；缺省时从当前时间起）
+ * @param {number} [wallMs] 当前事件的期望物理时间戳（ms）；缺省为 `Date.now()`
+ * @returns {{ wall: number, logical: number }} 新事件 HLC 的可序列化纯对象
+ */
+export function nextHlc(lastHlcJson, wallMs) {
+	const wall = typeof wallMs === 'number' && Number.isFinite(wallMs)
+		? Math.max(wallMs, Date.now())
+		: Date.now()
+	const remote = new HLC(wall, 0)
+	if (!lastHlcJson || typeof lastHlcJson.wall !== 'number')
+		return remote.toJSON()
+	const last = HLC.fromJSON(lastHlcJson)
+	return last.update(remote).toJSON()
+}

package/core/random_id.mjs

@@ -0,0 +1,9 @@
+import { randomUUID } from 'node:crypto'
+
+/**
+ * @param {string} prefix ID 前缀（如 channel_）
+ * @returns {string} 带前缀的随机 ID
+ */
+export function prefixedRandomId(prefix) {
+	return `${prefix}${randomUUID().replace(/-/g, '')}`
+}

package/crypto/channel.mjs

@@ -0,0 +1,101 @@
+/**
+ * Domain-key 信封：X25519 ECIES 包装与 AES-GCM 消息载荷（wire scheme 由消费方定义，如 ckg）。
+ * 解密 payload 不可脱离外层 DAG Ed25519 签名上下文单独传递或信任。
+ */
+import { Buffer } from 'node:buffer'
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto'
+
+import { unwrapKeyEcies, wrapKeyEcies } from './key.mjs'
+
+/** @type {'ckg'} 频道消息 content 加密 scheme */
+export const CKG_SCHEME = 'ckg'
+
+/** @typedef {{ ephemPub: string, iv: string, ciphertext: string, authTag: string }} EciesWrapBlob */
+
+/**
+ * 生成随机 32 字节频道密钥（hex）。
+ * @returns {string} 32 字节 hex 频道密钥
+ */
+export function generateChannelKey() {
+	return randomBytes(32).toString('hex')
+}
+
+/**
+ * X25519 ECIES 包装 K_ch 给成员 Ed25519 公钥。
+ * @param {string} channelKeyHex 32 字节 hex
+ * @param {string} memberEdPubKeyHex 64 位十六进制
+ * @returns {EciesWrapBlob} ECIES 包装结果
+ */
+export function wrapChannelKey(channelKeyHex, memberEdPubKeyHex) {
+	return wrapKeyEcies(channelKeyHex, memberEdPubKeyHex)
+}
+
+/**
+ * @param {EciesWrapBlob} wrap ECIES 密文
+ * @param {Uint8Array} myEdPrivKeySeed 32 字节 Ed25519 种子
+ * @returns {string | null} K_ch hex
+ */
+export function unwrapChannelKey(wrap, myEdPrivKeySeed) {
+	return unwrapKeyEcies(wrap, myEdPrivKeySeed)
+}
+
+/**
+ * @param {string} channelKeyHex K_ch
+ * @param {string} channelId 频道 id（AAD 盐）
+ * @param {number} generation 代际
+ * @returns {Buffer} 消息 AES-256 密钥
+ */
+function messageAesKey(channelKeyHex, channelId, generation) {
+	return Buffer.from(hkdfSync(
+		'sha256',
+		Buffer.from(channelKeyHex, 'hex'),
+		`ckg:${String(channelId)}:${String(generation)}`,
+		'',
+		32,
+	))
+}
+
+/**
+ * @param {string} plaintext UTF-8 / JSON 字符串
+ * @param {string} channelKeyHex K_ch
+ * @param {string} channelId 频道 ID
+ * @param {number} generation 密钥代际
+ * @returns {{ scheme: typeof CKG_SCHEME, channelId: string, generation: number, payload: string }} 频道密钥信封
+ */
+export function encryptWithChannelKey(plaintext, channelKeyHex, channelId, generation) {
+	const key = messageAesKey(channelKeyHex, channelId, generation)
+	const iv = randomBytes(12)
+	const cipher = createCipheriv('aes-256-gcm', key, iv)
+	const plain = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext, 'utf8')
+	const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()])
+	const authTag = cipher.getAuthTag()
+	return {
+		scheme: CKG_SCHEME,
+		channelId: String(channelId),
+		generation: Number(generation) || 0,
+		payload: `${iv.toString('base64')}.${ciphertext.toString('base64')}.${authTag.toString('base64')}`,
+	}
+}
+
+/**
+ * @param {{ scheme?: string, channelId?: string, generation?: number, payload: string }} envelope 频道密钥信封
+ * @param {string} channelKeyHex K_ch
+ * @param {string} channelId 频道 ID
+ * @returns {string | null} 明文 UTF-8
+ */
+export function decryptWithChannelKey(envelope, channelKeyHex, channelId) {
+	if (envelope?.scheme !== CKG_SCHEME || !envelope.payload) return null
+	try {
+		const parts = envelope.payload.split('.')
+		if (parts.length !== 3) return null
+		const generation = Number(envelope.generation) || 0
+		const key = messageAesKey(channelKeyHex, channelId, generation)
+		const iv = Buffer.from(parts[0], 'base64')
+		const ciphertext = Buffer.from(parts[1], 'base64')
+		const authTag = Buffer.from(parts[2], 'base64')
+		const decipher = createDecipheriv('aes-256-gcm', key, iv)
+		decipher.setAuthTag(authTag)
+		return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')
+	}
+	catch { return null }
+}