配对管理Skill pairing

---

名称: 配对 描述: “用户配对、认证和信任管理” 表情符号: “🔗”

配对 - 完整API参考

配对新用户到Clodds，管理信任级别，并跨渠道控制访问。

---

聊天命令

配对（新用户）

/pair                                       请求配对（生成代码）
/pair-code ABC123                           输入配对代码
/unpair                                     移除您的配对

管理员命令

/pairing list                               列出待处理请求
/pairing approve <code>                     批准配对请求
/pairing reject <code>                      拒绝配对请求
/pairing users                              列出配对用户
/pairing remove <user>                      移除用户配对

信任管理

/trust <user> owner                         授予所有者信任
/trust <user> paired                        标准信任
/trust list                                 列出信任级别

---

TypeScript API参考

创建配对服务

import { createPairingService } from 'clodds/pairing';

const pairing = createPairingService({
  // 代码设置
  codeLength: 8,
  codeExpiryMinutes: 60,
  maxPendingPerChannel: 3,

  // 自动批准设置
  autoApproveLocal: true,      // 自动批准本地主机
  autoApproveTailscale: true,  // 自动批准Tailscale IP
  autoApproveOwners: true,     // 所有者自动批准其请求

  // 存储
  storage: 'sqlite',
  dbPath: './pairing.db',
});

创建配对请求

// 用户请求配对
const request = await pairing.createPairingRequest({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
  username: 'johndoe',
  displayName: 'John Doe',
});

console.log(`配对代码: ${request.code}`);
console.log(`过期时间: ${request.expiresAt}`);
console.log(`分享此代码给管理员以获得批准`);

验证代码

// 检查代码是否有效
const valid = await pairing.validateCode({
  code: 'ABC123XY',
});

if (valid) {
  console.log(`有效代码用于用户: ${valid.username}`);
  console.log(`渠道: ${valid.channelId}`);
}

批准请求

// 管理员批准配对
await pairing.approveRequest({
  code: 'ABC123XY',
  approvedBy: 'admin-user-id',
  trustLevel: 'paired',
});

拒绝请求

// 管理员拒绝配对
await pairing.rejectRequest({
  code: 'ABC123XY',
  rejectedBy: 'admin-user-id',
  reason: '未知用户',
});

检查配对状态

// 检查用户是否配对
const isPaired = await pairing.isPaired({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

if (isPaired) {
  console.log('用户已配对，可以使用Clodds');
}

获取信任级别

const trust = await pairing.getTrustLevel({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

console.log(`信任级别: ${trust}`);
// 'owner' | 'paired' | 'stranger'

// 检查特定权限
if (trust === 'owner') {
  console.log('完整管理员访问');
} else if (trust === 'paired') {
  console.log('标准交易访问');
} else {
  console.log('无访问权限 - 必须先配对');
}

列出待处理请求

const pending = await pairing.listPendingRequests({
  channelId: 'telegram-123',  // 可选：按渠道过滤
});

for (const req of pending) {
  console.log(`代码: ${req.code}`);
  console.log(`用户: ${req.username} (${req.displayName})`);
  console.log(`请求时间: ${req.createdAt}`);
  console.log(`过期时间: ${req.expiresAt}`);
}

列出配对用户

const users = await pairing.listPairedUsers({
  channelId: 'telegram-123',  // 可选：按渠道过滤
});

for (const user of users) {
  console.log(`${user.username}: ${user.trustLevel}`);
  console.log(`  配对时间: ${user.pairedAt}`);
  console.log(`  批准者: ${user.approvedBy}`);
}

检查所有者状态

const isOwner = await pairing.isOwner({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

if (isOwner) {
  console.log('用户拥有所有者权限');
}

移除配对

// 移除用户的配对
await pairing.removePairing({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

---

信任级别

级别	访问权限
owner	完整管理员：批准用户、管理设置、交易
paired	标准：交易、投资组合、查询
stranger	无：必须先配对

---

配对代码格式

• 长度: 8个字符
• 字符: 大写字母 + 数字
• 排除: 0, O, 1, I, L（避免混淆）
• 示例: ABC234XY

---

自动批准规则

条件	行为
本地主机	自动批准，授予所有者信任
Tailscale IP	自动批准，授予所有者信任
所有者请求	自动批准其其他渠道

---

安全功能

功能	描述
代码过期	代码在1小时后过期
速率限制	每个渠道最多3个待处理
明确代码	无易混淆字符
审计追踪	记录谁在何时批准/拒绝

---

CLI管理员命令

# 列出待处理配对请求
clodds pairing list telegram

# 批准一个请求
clodds pairing approve ABC234XY

# 列出配对用户
clodds pairing users telegram

# 直接添加用户（绕过代码）
clodds pairing add telegram user-123

# 移除用户
clodds pairing remove telegram user-123

---

最佳实践

1. 安全分享代码 — 不要在公共渠道发布
2. 设置适当过期 — 对敏感系统使用更短时间
3. 定期审查待处理 — 不要让请求堆积
4. 谨慎使用所有者 — 大多数用户只需“paired”
5. 定期审计 — 审查谁有访问权限