Back to Details

pairing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pairing - Complete API Reference

配对 - 完整API参考

Pair new users to Clodds, manage trust levels, and control access across channels.
将新用户与Clodds配对，管理信任级别，并跨渠道控制访问权限。

Chat Commands

聊天命令

Pairing (New Users)

配对（新用户）

/pair                                       Request pairing (generates code)
/pair-code ABC123                           Enter pairing code
/unpair                                     Remove your pairing
/pair                                       请求配对（生成验证码）
/pair-code ABC123                           输入配对验证码
/unpair                                     解除配对

Admin Commands

管理员命令

/pairing list                               List pending requests
/pairing approve <code>                     Approve pairing request
/pairing reject <code>                      Reject pairing request
/pairing users                              List paired users
/pairing remove <user>                      Remove user pairing
/pairing list                               列出待处理的配对请求
/pairing approve <code>                     批准配对请求
/pairing reject <code>                      拒绝配对请求
/pairing users                              列出已配对用户
/pairing remove <user>                      移除用户配对

Trust Management

信任管理

/trust <user> owner                         Grant owner trust
/trust <user> paired                        Standard trust
/trust list                                 List trust levels
/trust <user> owner                         授予所有者信任级别
/trust <user> paired                        设置标准信任级别
/trust list                                 列出所有信任级别

TypeScript API Reference

TypeScript API参考

Create Pairing Service

创建配对服务

typescript
import { createPairingService } from 'clodds/pairing';

const pairing = createPairingService({
  // Code settings
  codeLength: 8,
  codeExpiryMinutes: 60,
  maxPendingPerChannel: 3,

  // Auto-approve settings
  autoApproveLocal: true,      // Auto-approve localhost
  autoApproveTailscale: true,  // Auto-approve Tailscale IPs
  autoApproveOwners: true,     // Owners auto-approve their requests

  // Storage
  storage: 'sqlite',
  dbPath: './pairing.db',
});
typescript
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',
});

Create Pairing Request

创建配对请求

typescript
// User requests pairing
const request = await pairing.createPairingRequest({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
  username: 'johndoe',
  displayName: 'John Doe',
});

console.log(`Pairing code: ${request.code}`);
console.log(`Expires: ${request.expiresAt}`);
console.log(`Share this code with an admin to get approved`);
typescript
// 用户发起配对请求
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(`请将此验证码分享给管理员以完成批准`);

Validate Code

验证验证码

typescript
// Check if code is valid
const valid = await pairing.validateCode({
  code: 'ABC123XY',
});

if (valid) {
  console.log(`Valid code for user: ${valid.username}`);
  console.log(`Channel: ${valid.channelId}`);
}
typescript
// 检查验证码是否有效
const valid = await pairing.validateCode({
  code: 'ABC123XY',
});

if (valid) {
  console.log(`验证码有效，所属用户：${valid.username}`);
  console.log(`渠道ID：${valid.channelId}`);
}

Approve Request

批准配对请求

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

Reject Request

拒绝配对请求

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

Check Pairing Status

检查配对状态

typescript
// Check if user is paired
const isPaired = await pairing.isPaired({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

if (isPaired) {
  console.log('User is paired and can use Clodds');
}
typescript
// 检查用户是否已配对
const isPaired = await pairing.isPaired({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

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

Get Trust Level

获取信任级别

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

console.log(`Trust level: ${trust}`);
// 'owner' | 'paired' | 'stranger'

// Check specific permission
if (trust === 'owner') {
  console.log('Full admin access');
} else if (trust === 'paired') {
  console.log('Standard trading access');
} else {
  console.log('No access - must pair first');
}
typescript
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('无访问权限 - 需先完成配对');
}

List Pending Requests

列出待处理请求

typescript
const pending = await pairing.listPendingRequests({
  channelId: 'telegram-123',  // Optional: filter by channel
});

for (const req of pending) {
  console.log(`Code: ${req.code}`);
  console.log(`User: ${req.username} (${req.displayName})`);
  console.log(`Requested: ${req.createdAt}`);
  console.log(`Expires: ${req.expiresAt}`);
}
typescript
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}`);
}

List Paired Users

列出已配对用户

typescript
const users = await pairing.listPairedUsers({
  channelId: 'telegram-123',  // Optional: filter by channel
});

for (const user of users) {
  console.log(`${user.username}: ${user.trustLevel}`);
  console.log(`  Paired: ${user.pairedAt}`);
  console.log(`  Approved by: ${user.approvedBy}`);
}
typescript
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}`);
}

Check Owner Status

检查所有者状态

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

if (isOwner) {
  console.log('User has owner privileges');
}
typescript
const isOwner = await pairing.isOwner({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

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

Remove Pairing

解除配对

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

Trust Levels

信任级别

LevelAccess
ownerFull admin: approve users, manage settings, trading
pairedStandard: trading, portfolio, queries
strangerNone: must pair first
级别访问权限
owner完整管理员：批准用户、管理设置、交易权限
paired标准权限：交易、投资组合、查询功能
stranger无权限：需先完成配对

Pairing Code Format

配对验证码格式

  • Length: 8 characters
  • Characters: Uppercase letters + numbers
  • Excludes: 0, O, 1, I, L (avoid confusion)
  • Example: 
    ABC234XY
  • 长度：8个字符
  • 字符类型：大写字母 + 数字
  • 排除字符：0、O、1、I、L（避免混淆）
  • 示例：
    ABC234XY

Auto-Approve Rules

自动批准规则

ConditionBehavior
LocalhostAuto-approve with owner trust
Tailscale IPAuto-approve with owner trust
Owner requestAuto-approve their other channels
条件行为
本地主机自动批准并授予所有者信任级别
Tailscale IP自动批准并授予所有者信任级别
所有者发起的请求自动批准其其他渠道的配对请求

Security Features

安全特性

FeatureDescription
Code expiryCodes expire after 1 hour
Rate limitingMax 3 pending per channel
Unambiguous codesNo confusable characters
Audit trailWho approved/rejected when
特性描述
验证码过期验证码1小时后过期
请求频率限制每个渠道最多允许3个待处理请求
无歧义验证码不使用易混淆字符
审计追踪记录谁在何时批准/拒绝了请求

CLI Admin Commands

CLI管理员命令

bash
undefined
bash
undefined

List pending pairing requests

列出待处理的配对请求

clodds pairing list telegram
clodds pairing list telegram

Approve a request

批准某个请求

clodds pairing approve ABC234XY
clodds pairing approve ABC234XY

List paired users

列出已配对用户

clodds pairing users telegram
clodds pairing users telegram

Add user directly (bypass code)

直接添加用户（跳过验证码流程）

clodds pairing add telegram user-123
clodds pairing add telegram user-123

Remove user

移除用户

clodds pairing remove telegram user-123

---
clodds pairing remove telegram user-123

---

Best Practices

最佳实践

  1. Share codes securely — Don't post in public channels
  2. Set expiry appropriately — Shorter for sensitive systems
  3. Review pending regularly — Don't let requests pile up
  4. Use owner sparingly — Most users only need 'paired'
  5. Audit periodically — Review who has access
  1. 安全分享验证码 — 不要在公开频道中发布验证码
  2. 合理设置过期时间 — 敏感系统可设置更短的过期时间
  3. 定期处理待请求 — 不要让请求堆积
  4. 谨慎授予所有者权限 — 大多数用户仅需'paired'级别权限
  5. 定期审计 — 检查用户访问权限情况