/pairing

name: pairing
description: "User pairing, authentication, and trust management"
emoji: "🔗"

Pairing - Complete API Reference

Pair new users to Clodds, manage trust levels, and control access across channels.

---

Chat Commands

Pairing (New Users)

/pair                                       Request pairing (generates code)
/pair-code ABC123                           Enter pairing code
/unpair                                     Remove your pairing

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

Trust Management

/trust <user> owner                         Grant owner trust
/trust <user> paired                        Standard trust
/trust list                                 List trust levels

---

TypeScript API Reference

Create Pairing Service

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',
});

Create Pairing Request

// 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`);

Validate Code

// 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}`);
}

Approve Request

// Admin approves pairing
await pairing.approveRequest({
  code: 'ABC123XY',
  approvedBy: 'admin-user-id',
  trustLevel: 'paired',
});

Reject Request

// Admin rejects pairing
await pairing.rejectRequest({
  code: 'ABC123XY',
  rejectedBy: 'admin-user-id',
  reason: 'Unknown user',
});

Check Pairing Status

// 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');
}

Get Trust Level

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');
}

List Pending Requests

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}`);
}

List Paired Users

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}`);
}

Check Owner Status

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

if (isOwner) {
  console.log('User has owner privileges');
}

Remove Pairing

// Remove user's pairing
await pairing.removePairing({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

---

Trust Levels

| Level | Access | |-------|--------| | **owner** | Full admin: approve users, manage settings, trading | | **paired** | Standard: trading, portfolio, queries | | **stranger** | None: must pair first |

---

Pairing Code Format

• **Length**: 8 characters
• **Characters**: Uppercase letters + numbers
• **Excludes**: 0, O, 1, I, L (avoid confusion)
• **Example**: `ABC234XY`

---

Auto-Approve Rules

| Condition | Behavior | |-----------|----------| | Localhost | Auto-approve with owner trust | | Tailscale IP | Auto-approve with owner trust | | Owner request | Auto-approve their other channels |

---

Security Features

| Feature | Description | |---------|-------------| | **Code expiry** | Codes expire after 1 hour | | **Rate limiting** | Max 3 pending per channel | | **Unambiguous codes** | No confusable characters | | **Audit trail** | Who approved/rejected when |

---

CLI Admin Commands

# List pending pairing requests
clodds pairing list telegram

# Approve a request
clodds pairing approve ABC234XY

# List paired users
clodds pairing users telegram

# Add user directly (bypass code)
clodds pairing add telegram user-123

# Remove user
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