Identity - Complete API Reference

Manage user identity, OAuth provider connections, and device authentication.

---

Chat Commands

View Identity

/identity                                   Show your identity
/identity status                            Auth status
/identity devices                           List linked devices

OAuth Providers

/identity providers                         List available providers
/identity link google                       Connect Google account
/identity link github                       Connect GitHub account
/identity unlink google                     Disconnect provider

Device Management

/identity device list                       List devices
/identity device name "Work Laptop"         Name this device
/identity device revoke <id>                Revoke device access
/identity device revoke-all                 Revoke all except current

Trust & Security

/identity trust                             View trust level
/identity sessions                          Active sessions
/identity session logout <id>               End session
/identity security                          Security settings

---

TypeScript API Reference

Create Identity Service

import { createIdentityService } from 'clodds/identity';

const identity = createIdentityService({
  // OAuth providers
  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,
    },
  },

  // Session settings
  sessionDurationMs: 86400000 * 30,  // 30 days
  deviceTrustDurationMs: 86400000 * 90,  // 90 days

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

Get User Identity

const user = await identity.getUser(userId);

console.log(`ID: ${user.id}`);
console.log(`Name: ${user.displayName}`);
console.log(`Email: ${user.email}`);
console.log(`Trust level: ${user.trustLevel}`);
console.log(`Created: ${user.createdAt}`);

Link OAuth Provider

// Generate OAuth URL
const authUrl = identity.getOAuthUrl('google', {
  redirectUri: 'https://your-domain.com/auth/callback',
  state: 'random-state-string',
  scopes: ['email', 'profile'],
});

// Handle callback
const result = await identity.handleOAuthCallback('google', {
  code: 'oauth-code-from-callback',
  state: 'random-state-string',
});

console.log(`Linked: ${result.provider}`);
console.log(`Email: ${result.email}`);

List Linked Providers

const providers = await identity.getLinkedProviders(userId);

for (const provider of providers) {
  console.log(`${provider.name}: ${provider.email}`);
  console.log(`  Linked: ${provider.linkedAt}`);
  console.log(`  Last used: ${provider.lastUsed}`);
}

Unlink Provider

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

Device Management

// List devices
const devices = await identity.getDevices(userId);

for (const device of devices) {
  console.log(`${device.id}: ${device.name || 'Unknown'}`);
  console.log(`  Type: ${device.type}`);  // 'desktop' | 'mobile' | 'tablet'
  console.log(`  Browser: ${device.browser}`);
  console.log(`  OS: ${device.os}`);
  console.log(`  Last seen: ${device.lastSeen}`);
  console.log(`  Current: ${device.isCurrent}`);
}

// Name device
await identity.nameDevice(userId, deviceId, 'Work Laptop');

// Revoke device
await identity.revokeDevice(userId, deviceId);

// Revoke all except current
await identity.revokeAllDevices(userId, { exceptCurrent: true });

Session Management

// List active sessions
const sessions = await identity.getSessions(userId);

for (const session of sessions) {
  console.log(`${session.id}: ${session.device}`);
  console.log(`  Started: ${session.startedAt}`);
  console.log(`  Last active: ${session.lastActive}`);
  console.log(`  IP: ${session.ip}`);
}

// End session
await identity.endSession(sessionId);

// End all sessions
await identity.endAllSessions(userId);

Trust Level

// Get trust level
const trust = await identity.getTrustLevel(userId);
console.log(`Trust: ${trust}`);  // 'owner' | 'paired' | 'stranger'

// Set trust level (admin only)
await identity.setTrustLevel(userId, 'paired');

---

Trust Levels

Level	Access
owner	Full admin access
paired	Standard user access
stranger	No access (must pair)

---

OAuth Providers

Provider	Scopes
Google	email, profile
GitHub	user:email
Discord	identify, email
Twitter	users.read

---

Device Types

Type	Detection
desktop	Windows, macOS, Linux
mobile	iOS, Android
tablet	iPad, Android tablet
unknown	Unrecognized UA

---

Best Practices

1. Link multiple providers — Backup auth methods
2. Review devices regularly — Revoke unused ones
3. Name your devices — Easier to identify
4. Check sessions — Monitor for suspicious access
5. Use strong auth — OAuth over passwords