identity/index.d.ts

declare module '@metatrom/identity' {
  /**
   * User identity (master identity)
   */
  export interface UserIdentity {
    userId: string; // Hash of master public key
    publicKey: Uint8Array; // Master public key
    mnemonic?: string; // Stored securely, only on this device
  }

  /**
   * Device identity (derived from user)
   */
  export interface DeviceIdentity {
    deviceId: string; // libp2p peer ID
    deviceName: string; // Human-readable name
    publicKey: Uint8Array; // Device public key (Ed25519)
    privateKey: Uint8Array; // Device private key (Ed25519)
    derivationPath: string; // HD derivation path
    createdAt: number;
    lastSeen?: number;
  }

  /**
   * Device information for remote devices
   */
  export interface DeviceInfo {
    deviceId: string;
    deviceName: string;
    multiaddrs: string[];
    isOnline: boolean;
    lastSeen: number;
  }

  /**
   * Configuration for identity manager
   */
  export interface IdentityConfig {
    storagePrefix?: string;
    mnemonicStrength?: 128 | 160 | 192 | 224 | 256;
    deviceNameProvider?: () => Promise<string>;
  }

  /**
   * Main identity management interface
   */
  export interface IIdentityManager {
    /**
     * Initialize the identity manager
     * Either loads existing identity or creates new one
     */
    initialize(): Promise<UserIdentity>;

    /**
     * Create a completely new user identity with mnemonic
     */
    createNewIdentity(): Promise<UserIdentity>;

    /**
     * Restore identity from mnemonic phrase
     */
    restoreFromMnemonic(mnemonic: string): Promise<UserIdentity>;

    /**
     * Create a new device identity derived from master
     */
    createDeviceIdentity(deviceName: string): Promise<DeviceIdentity>;

    /**
     * Get current device identity or create one if none exists
     */
    getCurrentDevice(): Promise<DeviceIdentity>;

    /**
     * List all registered devices for this user
     */
    getRegisteredDevices(): Promise<DeviceIdentity[]>;

    /**
     * Remove a device from the user's identity
     */
    removeDevice(deviceId: string): Promise<void>;

    /**
     * Clean up duplicate devices with the same base name
     * @returns Number of devices removed
     */
    cleanupDuplicateDevices(): Promise<number>;

    /**
     * Clean up inactive devices (except current device)
     * @param daysInactive - Number of days of inactivity before removal (default: 30)
     * @returns Number of devices removed
     */
    cleanupInactiveDevices(daysInactive?: number): Promise<number>;

    /**
     * Get the libp2p keypair for current device
     */
    getLibp2pKeypair(): Promise<{ privateKey: Uint8Array; publicKey: Uint8Array }>;

    /**
     * Update the current device's peer ID after libp2p generates it
     */
    updateDevicePeerId(peerId: string): Promise<void>;

    /**
     * Calculate what the peer ID will be for a given device index
     * Useful during pairing to predict the new device's peer ID
     */
    calculatePeerIdForIndex(deviceIndex: number): Promise<string>;

    /**
     * Export mnemonic for backup (should be done securely!)
     */
    getMnemonic(): string | undefined;

    /**
     * Get user identity
     */
    getUserIdentity(): UserIdentity | undefined;

    /**
     * Check if identity is initialized
     */
    isInitialized(): boolean;

    /**
     * Clear all identity data (dangerous!)
     */
    reset(): Promise<void>;

    /**
     * Broadcast peer ID update to other devices
     */
    broadcastPeerIdUpdate(
      oldPeerId: string,
      newPeerId: string,
      sendProtocolData?: (peerId: string, protocolId: string, data: Uint8Array) => Promise<void>,
    ): Promise<void>;
  }

  /**
   * Storage interface for identity persistence
   */
  export interface IIdentityStorage {
    setItem(key: string, value: string): Promise<void>;
    getItem(key: string): Promise<string | null>;
    removeItem(key: string): Promise<void>;
    clear(): Promise<void>;
  }

  /**
   * Factory interface for creating identity managers
   */
  export interface IIdentityFactory {
    create(config?: IdentityConfig): IIdentityManager;
  }

  // AsyncStorage type definition for dependency injection
  interface IAsyncStorage {
    setItem(key: string, value: string): Promise<void>;
    getItem(key: string): Promise<string | null>;
    removeItem(key: string): Promise<void>;
    getAllKeys(): Promise<string[]>;
    multiRemove(keys: string[]): Promise<void>;
  }

  // Platform interface for dependency injection
  interface IPlatform {
    OS: string;
  }

  /**
   * AsyncStorage adapter for React Native
   */
  export class AsyncStorageAdapter implements IIdentityStorage {
    constructor(asyncStorage: IAsyncStorage);
    setItem(key: string, value: string): Promise<void>;
    getItem(key: string): Promise<string | null>;
    removeItem(key: string): Promise<void>;
    clear(): Promise<void>;
  }

  /**
   * Identity Manager Implementation
   */
  export class IdentityManager implements IIdentityManager {
    constructor(storage: IIdentityStorage, config?: IdentityConfig);
    initialize(): Promise<UserIdentity>;
    createNewIdentity(): Promise<UserIdentity>;
    restoreFromMnemonic(mnemonic: string): Promise<UserIdentity>;
    createDeviceIdentity(deviceName: string): Promise<DeviceIdentity>;
    getCurrentDevice(): Promise<DeviceIdentity>;
    getRegisteredDevices(): Promise<DeviceIdentity[]>;
    removeDevice(deviceId: string): Promise<void>;
    cleanupDuplicateDevices(): Promise<number>;
    cleanupInactiveDevices(daysInactive?: number): Promise<number>;
    getLibp2pKeypair(): Promise<{ privateKey: Uint8Array; publicKey: Uint8Array }>;
    updateDevicePeerId(peerId: string): Promise<void>;
    calculatePeerIdForIndex(deviceIndex: number): Promise<string>;
    getMnemonic(): string | undefined;
    getUserIdentity(): UserIdentity | undefined;
    isInitialized(): boolean;
    reset(): Promise<void>;
    broadcastPeerIdUpdate(
      oldPeerId: string,
      newPeerId: string,
      sendProtocolData?: (peerId: string, protocolId: string, data: Uint8Array) => Promise<void>,
    ): Promise<void>;
  }

  /**
   * Factory for creating identity manager instances
   */
  export class IdentityFactory implements IIdentityFactory {
    static getInstance(platform?: IPlatform, asyncStorage?: IAsyncStorage): IdentityFactory;
    create(config?: IdentityConfig): IIdentityManager;
    static reset(): void;
  }

  /**
   * Create identity manager with dependency injection
   */
  export function createIdentityManager(
    config?: IdentityConfig,
    platform?: IPlatform,
    asyncStorage?: IAsyncStorage
  ): IIdentityManager;

  // Version information
  export const VERSION: string;
  export const PROTOCOL_VERSION: string;
}