@crossplatformai/device

Unified device fingerprint management plugin for cross-platform applications.

Overview

This plugin provides both client-side and server-side device fingerprint management, enabling secure device tracking and session management across web, mobile, desktop, and CLI platforms.

Architecture

plugins/device/
├── src/
│   ├── api/          # Server-side device management
│   │   ├── index.ts  # API exports and route creation
│   │   └── service.ts # Device session management logic
│   ├── ui/           # Client-side device management
│   │   ├── index.ts  # UI exports
│   │   ├── manager.ts # Device fingerprint manager
│   │   ├── cli.ts    # CLI-specific exports
│   │   └── storage/  # Platform-specific storage implementations
│   │       ├── web.ts # Browser localStorage
│   │       └── cli.ts # File system storage
│   ├── shared/       # Shared utilities
│   │   └── constants.ts # Common constants
│   ├── types.ts     # Shared TypeScript types
│   └── index.ts     # Main exports

Usage

Client-Side (UI)

// Web/Desktop
import { DeviceManager, webStorage } from '@crossplatformai/device/ui';

const deviceManager = new DeviceManager(webStorage);
const fingerprint = await deviceManager.getDeviceFingerprint();

// CLI
import { DeviceManager, cliStorage } from '@crossplatformai/device/ui/cli';

const deviceManager = new DeviceManager(cliStorage);
const fingerprint = await deviceManager.getDeviceFingerprint();

// React Native (provide AsyncStorage implementation)
import { DeviceManager } from '@crossplatformai/device/ui';
import AsyncStorage from '@react-native-async-storage/async-storage';

const deviceManager = new DeviceManager(AsyncStorage);

Server-Side (API)

import { findOrCreateDeviceSession } from '@crossplatformai/device/api';

// In your auth verification endpoint
const result = await findOrCreateDeviceSession(
  { storage, cache },
  userId,
  deviceFingerprint,
  platform,
  ipAddress,
  userAgent
);

// Returns:
// {
//   session: Session object
//   deviceFingerprint: string (new or existing)
//   isNewDevice: boolean
// }

Import Paths

• @crossplatformai/device - All exports (convenience)
• @crossplatformai/device/api - Server-side only
• @crossplatformai/device/ui - Client-side only
• @crossplatformai/device/ui/cli - CLI-specific
• @crossplatformai/device/types - Type definitions
• @crossplatformai/device/constants - Shared constants

Features

Client-Side

• Persistent device fingerprint storage
• Cross-platform support (web, mobile, desktop, CLI)
• Survives sign-out/sign-in cycles
• Memory + persistent storage caching

Server-Side

• Device session management
• Automatic device deduplication
• Session activity tracking
• Integration with auth plugin

Testing

pnpm test         # Run tests
pnpm check-types  # Type checking
pnpm lint         # Linting

Dependencies

• Server: hono, drizzle-orm, nanoid, zod
• Client: Platform-specific storage implementations
• Shared: @repo/core

Migration from Separate Plugins

If migrating from @repo/ui-device and @repo/api-device:

1. Update package.json dependencies:

   - "@repo/ui-device": "workspace:*",
   - "@repo/api-device": "workspace:*",
   + "@crossplatformai/device": "workspace:*",

2. Update imports:

   - import { DeviceManager } from '@repo/ui-device';
   + import { DeviceManager } from '@crossplatformai/device/ui';
      
   - import { findOrCreateDeviceSession } from '@repo/api-device';
   + import { findOrCreateDeviceSession } from '@crossplatformai/device/api';

3. Run pnpm install to update dependencies