binance-api/specs/001-credential-manager/contracts/credential-manager.ts

/**
 * 凭证管理模块 - API契约定义
 *
 * 本文件定义了凭证管理模块的所有公开接口，供其他模块调用。
 * 遵循库优先架构原则，所有接口都是类型安全的TypeScript定义。
 */

// ============================================================================
// 核心类型定义
// ============================================================================

export enum Platform {
  PACIFICA = 'pacifica',
  ASTER = 'aster',
  BINANCE = 'binance'
}

export enum SignatureType {
  ED25519 = 'ed25519',
  ECDSA_ETHEREUM = 'ecdsa-ethereum',
  HMAC_SHA256 = 'hmac-sha256'
}

export enum AccountStatus {
  LOADING = 'loading',
  ACTIVE = 'active',
  ERROR = 'error',
  REMOVED = 'removed'
}

// ============================================================================
// 凭证类型定义
// ============================================================================

export interface PacificaCredentials {
  type: 'pacifica';
  privateKey: string; // 64字符十六进制Ed25519私钥
}

export interface AsterCredentials {
  type: 'aster';
  privateKey: string; // 以太坊格式私钥
}

export interface BinanceCredentials {
  type: 'binance';
  apiKey: string;
  secretKey: string;
}

export type Credentials = PacificaCredentials | AsterCredentials | BinanceCredentials;

// ============================================================================
// 核心实体接口
// ============================================================================

export interface Account {
  id: string;
  platform: Platform;
  credentials: Credentials;
  status?: AccountStatus;
  metadata?: {
    alias?: string;
    description?: string;
    [key: string]: any;
  };
}

export interface SignResult {
  success: boolean;
  signature?: string;
  algorithm: string;
  timestamp: Date;
  error?: string;
}

// ============================================================================
// 主要接口定义
// ============================================================================

/**
 * 凭证管理器主接口
 * 提供配置加载、账户管理、签名服务等核心功能
 */
export interface ICredentialManager {
  /**
   * 从配置文件加载账户信息
   * @param configPath 配置文件路径
   * @returns 加载结果
   */
  loadConfig(configPath: string): Promise<LoadResult>;

  /**
   * 开始监听配置文件变更
   * @param configPath 配置文件路径
   * @param callback 变更回调函数
   */
  watchConfig(configPath: string, callback?: (accounts: Account[]) => void): void;

  /**
   * 停止监听配置文件变更
   */
  stopWatching(): void;

  /**
   * 获取账户信息
   * @param accountId 账户ID
   * @returns 账户信息，如果不存在返回null
   */
  getAccount(accountId: string): Account | null;

  /**
   * 列出所有账户
   * @returns 账户列表
   */
  listAccounts(): Account[];

  /**
   * 执行签名操作
   * @param accountId 账户ID
   * @param message 要签名的消息
   * @returns 签名结果
   */
  sign(accountId: string, message: Uint8Array): Promise<SignResult>;

  /**
   * 验证签名
   * @param accountId 账户ID
   * @param message 原始消息
   * @param signature 签名字符串
   * @returns 验证结果
   */
  verify(accountId: string, message: Uint8Array, signature: string): Promise<boolean>;
}

/**
 * 配置加载器接口
 * 负责从配置文件加载账户信息并监听文件变更
 */
export interface IConfigLoader {
  /**
   * 加载配置文件
   * @param filePath 配置文件路径
   * @returns 加载结果
   */
  loadConfig(filePath: string): Promise<LoadResult>;

  /**
   * 监听配置文件变更
   * @param filePath 配置文件路径
   * @param callback 变更回调函数
   */
  watchConfig(filePath: string, callback: (accounts: Account[]) => void): void;

  /**
   * 停止监听
   */
  stopWatching(): void;
}

/**
 * 签名器接口
 * 提供统一的签名服务，支持多种平台
 */
export interface ISigner {
  /**
   * 注册平台签名策略
   * @param platform 平台类型
   * @param strategy 签名策略
   */
  registerStrategy(platform: Platform, strategy: ISignerStrategy): void;

  /**
   * 执行签名
   * @param accountId 账户ID
   * @param message 要签名的消息
   * @returns 签名结果
   */
  sign(accountId: string, message: Uint8Array): Promise<SignResult>;

  /**
   * 验证签名
   * @param accountId 账户ID
   * @param message 原始消息
   * @param signature 签名字符串
   * @returns 验证结果
   */
  verify(accountId: string, message: Uint8Array, signature: string): Promise<boolean>;
}

/**
 * 签名策略接口
 * 每个平台实现自己的签名策略
 */
export interface ISignerStrategy {
  platform: Platform;

  /**
   * 执行签名
   * @param message 要签名的消息
   * @param credentials 凭证信息
   * @returns 签名字符串
   */
  sign(message: Uint8Array, credentials: Credentials): Promise<string>;

  /**
   * 验证签名
   * @param message 原始消息
   * @param signature 签名字符串
   * @param publicKey 公钥
   * @returns 验证结果
   */
  verify(message: Uint8Array, signature: string, publicKey: string): Promise<boolean>;
}

/**
 * 平台检测器接口
 * 用于智能识别账户所属平台
 */
export interface IPlatformDetector {
  /**
   * 检测置信度
   */
  confidence: number;

  /**
   * 检测平台类型
   * @param credentials 凭证信息
   * @returns 平台类型，如果无法识别返回null
   */
  detect(credentials: any): Platform | null;
}

// ============================================================================
// 请求/响应类型
// ============================================================================

export interface LoadResult {
  success: boolean;
  accounts: Account[];
  errors?: string[];
  loadTime: number; // 加载耗时（毫秒）
}

export interface ConfigFile {
  version: string;
  accounts: AccountConfig[];
}

export interface AccountConfig {
  id: string;
  platform: Platform;
  credentials: Credentials;
  metadata?: Record<string, any>;
}

// ============================================================================
// 错误类型
// ============================================================================

export enum ErrorType {
  CONFIG_LOAD_ERROR = 'config_load_error',
  VALIDATION_ERROR = 'validation_error',
  SIGNATURE_ERROR = 'signature_error',
  PLATFORM_DETECTION_ERROR = 'platform_detection_error'
}

export interface CredentialError {
  type: ErrorType;
  message: string;
  accountId?: string;
  timestamp: Date;
  details?: any;
}

export class CredentialManagerError extends Error {
  constructor(
    message: string,
    public readonly type: ErrorType,
    public readonly details?: any
  ) {
    super(message);
    this.name = 'CredentialManagerError';
  }
}

// ============================================================================
// 工厂函数接口
// ============================================================================

/**
 * 凭证管理器工厂接口
 */
export interface ICredentialManagerFactory {
  /**
   * 创建凭证管理器实例
   * @param options 配置选项
   * @returns 凭证管理器实例
   */
  create(options?: CredentialManagerOptions): Promise<ICredentialManager>;
}

export interface CredentialManagerOptions {
  /**
   * 是否启用文件监听
   * @default true
   */
  enableFileWatching?: boolean;

  /**
   * 签名超时时间（毫秒）
   * @default 30000
   */
  signTimeout?: number;

  /**
   * 是否启用日志记录
   * @default true
   */
  enableLogging?: boolean;

  /**
   * 日志级别
   * @default 'info'
   */
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
}

// ============================================================================
// 工具函数类型
// ============================================================================

/**
 * 平台检测工具
 */
export interface IPlatformDetectionService {
  /**
   * 注册平台检测器
   * @param detector 平台检测器
   */
  registerDetector(detector: IPlatformDetector): void;

  /**
   * 检测平台类型
   * @param credentials 凭证信息
   * @returns 检测结果
   */
  detectPlatform(credentials: any): DetectionResult;
}

export interface DetectionResult {
  platform: Platform | null;
  confidence: number;
  detectors: Array<{
    detector: string;
    platform: Platform | null;
    confidence: number;
  }>;
}

// ============================================================================
// 导出所有类型
// ============================================================================

export {
  ICredentialManager as CredentialManager,
  IConfigLoader as ConfigLoader,
  ISigner as Signer,
  ISignerStrategy as SignerStrategy,
  IPlatformDetector as PlatformDetector,
  ICredentialManagerFactory as CredentialManagerFactory,
  IPlatformDetectionService as PlatformDetectionService
};