Device Key Management

Device keys are cryptographic keys used by email and phone signers to authorize transactions. This guide covers everything you need to know about managing device keys.

Overview

Device keys enable non-custodial authentication where keys are stored locally on the device. The SDK provides automatic resolution, validation, and caching to simplify device key management.

Key Concepts

Basic Usage

Creating a Signer with Device Key

import { 
  createEmailSignerHelper,
  createLocalStorageAdapter 
} from 'cilantro-sdk/helpers';

const storage = createLocalStorageAdapter();

// Device key is generated automatically
const signer = await createEmailSignerHelper('wallet-id', {
  email: 'user@example.com',
  deviceKeyManager: storage
});

Getting a Keypair

import { getEmailSignerKeypair } from 'cilantro-sdk/helpers';

// SDK automatically:
// 1. Fetches signer from API
// 2. Extracts devicePublicKey and deviceId
// 3. Resolves device key from storage
// 4. Validates device key matches API
const keypair = await getEmailSignerKeypair(
  'wallet-id',
  'signer-id',
  { deviceKeyManager: storage }
);

Storage Adapters

LocalStorage (Browser)

import { createLocalStorageAdapter } from 'cilantro-sdk/helpers';

const storage = createLocalStorageAdapter();

FileSystem (Node.js)

import { createFileSystemAdapter } from 'cilantro-sdk/helpers';

const storage = createFileSystemAdapter({
  basePath: './device-keys'
});

Memory (Testing)

import { createMemoryAdapter } from 'cilantro-sdk/helpers';

const storage = createMemoryAdapter();

Device Key Operations

Generate Device Key

import { generateDeviceKeyPair } from 'cilantro-sdk/helpers';

const keyPair = await generateDeviceKeyPair({
  deviceKeyManager: storage
});

Get Device Public Key

import { getDevicePublicKey } from 'cilantro-sdk/helpers';

const deviceKey = await getDevicePublicKey({
  deviceKeyManager: storage
});

Rotate Device Key

import { rotateDeviceKey } from 'cilantro-sdk/helpers';

await rotateDeviceKey('old-device-id', {
  deviceKeyManager: storage
});

Find Device Key

import { findDeviceKeyByPublicKey } from 'cilantro-sdk/helpers';

const deviceKey = await findDeviceKeyByPublicKey(
  'device-public-key',
  { deviceKeyManager: storage }
);

Multi-Device Support

Adding Multiple Devices

import { addDeviceIdentityToSigner } from 'cilantro-sdk/helpers';

// Add device from another browser/device
await addDeviceIdentityToSigner(
  'wallet-id',
  'signer-id',
  {
    devicePublicKey: 'new-device-public-key',
    deviceId: 'new-device-id'
  }
);

Getting Best Device

import { getBestDeviceIdentity } from 'cilantro-sdk/helpers';

const bestDevice = await getBestDeviceIdentity(
  'wallet-id',
  'signer-id',
  { deviceKeyManager: storage }
);

Listing All Devices

import { listAllDeviceKeys } from 'cilantro-sdk/helpers';

const deviceKeys = await listAllDeviceKeys({
  deviceKeyManager: storage
});

Validation

Validate Device Key

import { validateDeviceKey } from 'cilantro-sdk/helpers';

const isValid = await validateDeviceKey(
  'wallet-id',
  'signer-id',
  'device-public-key',
  { deviceKeyManager: storage }
);

if (!isValid) {
  // Handle invalid device key
}

Resolve Device Key

import { resolveDeviceKey } from 'cilantro-sdk/helpers';

const deviceKey = await resolveDeviceKey(
  'wallet-id',
  'signer-id',
  { deviceKeyManager: storage }
);

Error Handling

See the Error Handling Guide for detailed information on handling device key errors.

Best Practices