---

name: identity description: “用户身份、OAuth连接和设备管理” emoji: “🪪”

身份 - 完整API参考

管理用户身份、OAuth提供商连接和设备认证。

---

聊天命令

查看身份

/identity                                   显示您的身份
/identity status                           认证状态
/identity devices                           列出链接的设备

OAuth提供商

/identity providers                         列出可用的提供商
/identity link google                      连接Google账户
/identity link github                      连接GitHub账户
/identity unlink google                     断开提供商连接

设备管理

/identity device list                       列出设备
/identity device name "工作笔记本电脑"         为此设备命名
/identity device revoke <id>                撤销设备访问权限
/identity device revoke-all                 除了当前设备外全部撤销

信任与安全

/identity trust                             查看信任等级
/identity sessions                          活跃会话
/identity session logout <id>               结束会话
/identity security                          安全设置

---

TypeScript API参考

创建身份服务

import { createIdentityService } from 'clodds/identity';

const identity = createIdentityService({
  // OAuth提供商
  providers: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    },
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
  },

  // 会话设置
  sessionDurationMs: 86400000 * 30,  // 30天
  deviceTrustDurationMs: 86400000 * 90,  // 90天

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

获取用户身份

const user = await identity.getUser(userId);

console.log(`ID: ${user.id}`);
console.log(`姓名: ${user.displayName}`);
console.log(`电子邮件: ${user.email}`);
console.log(`信任等级: ${user.trustLevel}`);
console.log(`创建时间: ${user.createdAt}`);

链接OAuth提供商

// 生成OAuth URL
const authUrl = identity.getOAuthUrl('google', {
  redirectUri: 'https://your-domain.com/auth/callback',
  state: '随机状态字符串',
  scopes: ['email', 'profile'],
});

// 处理回调
const result = await identity.handleOAuthCallback('google', {
  code: '来自回调的oauth代码',
  state: '随机状态字符串',
});

console.log(`已链接: ${result.provider}`);
console.log(`电子邮件: ${result.email}`);

列出链接的提供商

const providers = await identity.getLinkedProviders(userId);

for (const provider of providers) {
  console.log(`${provider.name}: ${provider.email}`);
  console.log(`  链接时间: ${provider.linkedAt}`);
  console.log(`  最后使用: ${provider.lastUsed}`);
}

取消链接提供商

await identity.unlinkProvider(userId, 'google');

设备管理

// 列出设备
const devices = await identity.getDevices(userId);

for (const device of devices) {
  console.log(`${device.id}: ${device.name || '未知'}`);
  console.log(`  类型: ${device.type}`);  // 'desktop' | 'mobile' | 'tablet'
  console.log(`  浏览器: ${device.browser}`);
  console.log(`  操作系统: ${device.os}`);
  console.log(`  最后看到: ${device.lastSeen}`);
  console.log(`  当前: ${device.isCurrent}`);
}

// 命名设备
await identity.nameDevice(userId, deviceId, '工作笔记本电脑');

// 撤销设备
await identity.revokeDevice(userId, deviceId);

// 除了当前设备外全部撤销
await identity.revokeAllDevices(userId, { exceptCurrent: true });

会话管理

// 列出活跃会话
const sessions = await identity.getSessions(userId);

for (const session of sessions) {
  console.log(`${session.id}: ${session.device}`);
  console.log(`  开始时间: ${session.startedAt}`);
  console.log(`  最后活跃: ${session.lastActive}`);
  console.log(`  IP: ${session.ip}`);
}

// 结束会话
await identity.endSession(sessionId);

// 结束所有会话
await identity.endAllSessions(userId);

信任等级

// 获取信任等级
const trust = await identity.getTrustLevel(userId);
console.log(`信任: ${trust}`);  // 'owner' | 'paired' | 'stranger'

// 设置信任等级（仅限管理员）
await identity.setTrustLevel(userId, 'paired');

---

信任等级

等级	访问权限
owner	完全管理员访问权限
paired	标准用户访问权限
stranger	无访问权限（必须配对）

---

OAuth提供商

提供商	范围
Google	email, profile
GitHub	user:email
Discord	identify, email
Twitter	users.read

---

设备类型

类型	检测
desktop	Windows, macOS, Linux
mobile	iOS, Android
tablet	iPad, Android平板
unknown	无法识别的UA

---

最佳实践

1. 链接多个提供商 — 备份认证方法
2. 定期审查设备 — 撤销未使用的设备
3. 为您的设备命名 — 更容易识别
4. 检查会话 — 监控可疑访问
5. 使用强认证 — OAuth优于密码