@cmdoss/memwal-sdk 0.6.0

package/src/config/validation.ts

@@ -0,0 +1,71 @@
+/**
+ * Configuration Validation
+ * 
+ * Validates PDW configuration and provides helpful error messages
+ */
+
+import type { PDWConfig } from '../types';
+
+export class ConfigurationError extends Error {
+  constructor(message: string) {
+    super(`PDW Configuration Error: ${message}`);
+    this.name = 'ConfigurationError';
+  }
+}
+
+export function validateConfig(config: Partial<PDWConfig>): PDWConfig {
+  const errors: string[] = [];
+
+  // Validate required fields
+  if (!config.packageId || config.packageId === '0x0') {
+    console.warn('PDW SDK: packageId not configured. Please set a valid deployed package ID.');
+  }
+
+  // Validate encryption config
+  if (config.encryptionConfig?.enabled && 
+      (!config.encryptionConfig.keyServers || config.encryptionConfig.keyServers.length === 0)) {
+    console.warn('PDW SDK: Encryption is enabled but no key servers configured. Some features may not work.');
+  }
+
+  // Validate threshold configuration
+  if (config.encryptionConfig?.policyConfig?.threshold) {
+    const threshold = config.encryptionConfig.policyConfig.threshold;
+    if (threshold < 1) {
+      errors.push('Encryption threshold must be at least 1');
+    }
+  }
+
+  // Validate storage config
+  if (config.storageConfig?.provider && !['walrus', 'local'].includes(config.storageConfig.provider)) {
+    errors.push('Storage provider must be either "walrus" or "local"');
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigurationError(errors.join('; '));
+  }
+
+  return config as PDWConfig;
+}
+
+export function mergeConfigs(base: PDWConfig, overrides: Partial<PDWConfig>): PDWConfig {
+  return {
+    ...base,
+    ...overrides,
+    encryptionConfig: {
+      enabled: true,
+      ...base.encryptionConfig,
+      ...overrides.encryptionConfig,
+      policyConfig: {
+        ...base.encryptionConfig?.policyConfig,
+        ...overrides.encryptionConfig?.policyConfig,
+      },
+    },
+    storageConfig: {
+      provider: 'walrus' as const,
+      cacheEnabled: true,
+      encryptionEnabled: true,
+      ...base.storageConfig,
+      ...overrides.storageConfig,
+    },
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Core Module - Barrel Export
+ *
+ * Re-exports all core types, interfaces, and base classes for the PDW SDK.
+ *
+ * All type definitions are in ./types/index.ts
+ * This file only provides re-exports for convenience.
+ */
+
+// Re-export core interfaces and base classes
+export * from './interfaces';
+
+// Re-export all types from the types module
+export * from './types';

package/src/core/interfaces/IService.ts

@@ -0,0 +1,307 @@
+/**
+ * Base Service Interface
+ * 
+ * Defines the standard interface that all services in the PDW SDK should implement.
+ * Provides consistent lifecycle management, error handling, logging, and metrics.
+ */
+
+/**
+ * Service lifecycle states
+ */
+export enum ServiceState {
+  UNINITIALIZED = 'uninitialized',
+  INITIALIZING = 'initializing',
+  READY = 'ready',
+  ERROR = 'error',
+  DESTROYED = 'destroyed',
+}
+
+/**
+ * Service configuration base interface
+ */
+export interface IServiceConfig {
+  /** Service name for logging and metrics */
+  name?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Enable metrics collection */
+  enableMetrics?: boolean;
+  /** Custom logger instance */
+  logger?: ILogger;
+}
+
+/**
+ * Logger interface for consistent logging across services
+ */
+export interface ILogger {
+  debug(message: string, context?: Record<string, any>): void;
+  info(message: string, context?: Record<string, any>): void;
+  warn(message: string, context?: Record<string, any>): void;
+  error(message: string, error?: Error, context?: Record<string, any>): void;
+}
+
+/**
+ * Service metrics interface
+ */
+export interface IServiceMetrics {
+  /** Total number of operations performed */
+  operationCount: number;
+  /** Total number of errors encountered */
+  errorCount: number;
+  /** Average operation duration in milliseconds */
+  averageDuration: number;
+  /** Last operation timestamp */
+  lastOperationTime?: number;
+  /** Service uptime in milliseconds */
+  uptime: number;
+  /** Custom metrics specific to the service */
+  custom?: Record<string, number>;
+}
+
+/**
+ * Base service interface that all services should implement
+ */
+export interface IService {
+  /**
+   * Service name for identification
+   */
+  readonly name: string;
+
+  /**
+   * Current service state
+   */
+  readonly state: ServiceState;
+
+  /**
+   * Initialize the service
+   * Should be called before using the service
+   * @returns Promise that resolves when initialization is complete
+   */
+  initialize?(): Promise<void>;
+
+  /**
+   * Destroy the service and cleanup resources
+   * Should be called when the service is no longer needed
+   * @returns Promise that resolves when cleanup is complete
+   */
+  destroy?(): Promise<void>;
+
+  /**
+   * Reset the service to initial state
+   * Useful for testing or recovering from errors
+   * @returns Promise that resolves when reset is complete
+   */
+  reset?(): Promise<void>;
+
+  /**
+   * Get service health status
+   * @returns Health check result
+   */
+  getHealth?(): Promise<ServiceHealth>;
+
+  /**
+   * Get service metrics
+   * @returns Current service metrics
+   */
+  getMetrics?(): IServiceMetrics;
+}
+
+/**
+ * Service health check result
+ */
+export interface ServiceHealth {
+  /** Whether the service is healthy */
+  healthy: boolean;
+  /** Service state */
+  state: ServiceState;
+  /** Health check timestamp */
+  timestamp: number;
+  /** Optional error message if unhealthy */
+  error?: string;
+  /** Additional health details */
+  details?: Record<string, any>;
+}
+
+/**
+ * Default console logger implementation
+ */
+export class ConsoleLogger implements ILogger {
+  constructor(private serviceName: string, private debugEnabled: boolean = false) {}
+
+  debug(message: string, context?: Record<string, any>): void {
+    if (this.debugEnabled) {
+      console.debug(`[${this.serviceName}] ${message}`, context || '');
+    }
+  }
+
+  info(message: string, context?: Record<string, any>): void {
+    console.log(`[${this.serviceName}] ${message}`, context || '');
+  }
+
+  warn(message: string, context?: Record<string, any>): void {
+    console.warn(`[${this.serviceName}] ${message}`, context || '');
+  }
+
+  error(message: string, error?: Error, context?: Record<string, any>): void {
+    console.error(`[${this.serviceName}] ${message}`, error, context || '');
+  }
+}
+
+/**
+ * Abstract base service class with common functionality
+ */
+export abstract class BaseService implements IService {
+  protected _state: ServiceState = ServiceState.UNINITIALIZED;
+  protected _logger: ILogger;
+  protected _metrics: IServiceMetrics;
+  protected _startTime: number;
+
+  constructor(protected config: IServiceConfig) {
+    this._logger = config.logger || new ConsoleLogger(
+      config.name || this.constructor.name,
+      config.debug || false
+    );
+    
+    this._startTime = Date.now();
+    
+    this._metrics = {
+      operationCount: 0,
+      errorCount: 0,
+      averageDuration: 0,
+      uptime: 0,
+      custom: {},
+    };
+  }
+
+  get name(): string {
+    return this.config.name || this.constructor.name;
+  }
+
+  get state(): ServiceState {
+    return this._state;
+  }
+
+  async initialize(): Promise<void> {
+    if (this._state !== ServiceState.UNINITIALIZED) {
+      this._logger.warn('Service already initialized', { state: this._state });
+      return;
+    }
+
+    this._state = ServiceState.INITIALIZING;
+    this._logger.info('Initializing service...');
+
+    try {
+      await this.onInitialize();
+      this._state = ServiceState.READY;
+      this._logger.info('Service initialized successfully');
+    } catch (error) {
+      this._state = ServiceState.ERROR;
+      this._logger.error('Service initialization failed', error as Error);
+      throw error;
+    }
+  }
+
+  async destroy(): Promise<void> {
+    this._logger.info('Destroying service...');
+    
+    try {
+      await this.onDestroy();
+      this._state = ServiceState.DESTROYED;
+      this._logger.info('Service destroyed successfully');
+    } catch (error) {
+      this._logger.error('Service destruction failed', error as Error);
+      throw error;
+    }
+  }
+
+  async reset(): Promise<void> {
+    this._logger.info('Resetting service...');
+    
+    try {
+      await this.onReset();
+      this._metrics = {
+        operationCount: 0,
+        errorCount: 0,
+        averageDuration: 0,
+        uptime: 0,
+        custom: {},
+      };
+      this._logger.info('Service reset successfully');
+    } catch (error) {
+      this._logger.error('Service reset failed', error as Error);
+      throw error;
+    }
+  }
+
+  async getHealth(): Promise<ServiceHealth> {
+    return {
+      healthy: this._state === ServiceState.READY,
+      state: this._state,
+      timestamp: Date.now(),
+      details: {
+        uptime: Date.now() - this._startTime,
+        operationCount: this._metrics.operationCount,
+        errorCount: this._metrics.errorCount,
+      },
+    };
+  }
+
+  getMetrics(): IServiceMetrics {
+    return {
+      ...this._metrics,
+      uptime: Date.now() - this._startTime,
+    };
+  }
+
+  /**
+   * Track an operation for metrics
+   */
+  protected async trackOperation<T>(
+    operationName: string,
+    operation: () => Promise<T>
+  ): Promise<T> {
+    const startTime = performance.now();
+    
+    try {
+      this._logger.debug(`Starting operation: ${operationName}`);
+      const result = await operation();
+      
+      const duration = performance.now() - startTime;
+      this.updateMetrics(duration);
+      
+      this._logger.debug(`Completed operation: ${operationName}`, { duration });
+      return result;
+    } catch (error) {
+      this._metrics.errorCount++;
+      this._logger.error(`Operation failed: ${operationName}`, error as Error);
+      throw error;
+    }
+  }
+
+  /**
+   * Update metrics with operation duration
+   */
+  private updateMetrics(duration: number): void {
+    this._metrics.operationCount++;
+    
+    // Calculate rolling average
+    const totalDuration = this._metrics.averageDuration * (this._metrics.operationCount - 1);
+    this._metrics.averageDuration = (totalDuration + duration) / this._metrics.operationCount;
+  }
+
+  /**
+   * Hook for service-specific initialization
+   */
+  protected abstract onInitialize(): Promise<void>;
+
+  /**
+   * Hook for service-specific destruction
+   */
+  protected abstract onDestroy(): Promise<void>;
+
+  /**
+   * Hook for service-specific reset
+   */
+  protected abstract onReset(): Promise<void>;
+}
+

package/src/core/interfaces/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Core Interfaces - Barrel Export
+ * 
+ * Exports all core interfaces and base classes for the PDW SDK.
+ */
+
+export * from './IService';
+

package/src/core/types/capability.ts

@@ -0,0 +1,297 @@
+/**
+ * Capability-Based Architecture Types for Personal Data Wallet SDK
+ *
+ * This module defines the TypeScript interfaces for the new capability-based
+ * access control system following SEAL PrivateData pattern.
+ *
+ * Key concepts:
+ * - MemoryCap: Capability object for app context access
+ * - Object ownership = access permission (SEAL idiomatic)
+ * - Transfer capability = share access
+ * - Burn capability = revoke access
+ *
+ * @see CAPABILITY-ARCHITECTURE-SUMMARY.md
+ */
+
+/**
+ * Memory capability object - core unit of access control
+ *
+ * Owns this object = can decrypt memories for this app context
+ * Can be transferred to share access with others
+ * Burn to permanently revoke access
+ */
+export interface MemoryCap {
+  /** Sui object ID of the capability */
+  id: string;
+  /** Random nonce for SEAL key derivation */
+  nonce: string;
+  /** Application context identifier (e.g., "MEMO", "HEALTH") */
+  appId: string;
+  /** Owner address (who can call seal_approve) */
+  owner: string;
+  /** Creation timestamp (epoch) */
+  createdAt?: number;
+}
+
+/**
+ * Options for creating a new MemoryCap
+ */
+export interface CreateMemoryCapOptions {
+  /** Application identifier (e.g., "MEMO", "HEALTH") */
+  appId: string;
+}
+
+/**
+ * Options for transferring a MemoryCap
+ */
+export interface TransferCapOptions {
+  /** Object ID of the capability to transfer */
+  capId: string;
+  /** Recipient address */
+  recipient: string;
+}
+
+/**
+ * Options for burning (revoking) a MemoryCap
+ */
+export interface BurnCapOptions {
+  /** Object ID of the capability to burn */
+  capId: string;
+}
+
+/**
+ * Options for SEAL approval
+ */
+export interface SealApproveOptions {
+  /** Reference to the MemoryCap object */
+  capId: string;
+  /** SEAL key ID to validate */
+  keyId: string;
+}
+
+/**
+ * Result of querying user's capabilities
+ */
+export interface MemoryCapList {
+  /** All capabilities owned by the user */
+  capabilities: MemoryCap[];
+  /** Total count */
+  count: number;
+}
+
+/**
+ * Options for filtering capabilities
+ */
+export interface ListCapsOptions {
+  /** Filter by specific app ID */
+  appId?: string;
+  /** User address (defaults to current signer) */
+  userAddress?: string;
+}
+
+/**
+ * Options for getting or creating a capability
+ */
+export interface GetOrCreateCapOptions {
+  /** Application identifier */
+  appId: string;
+  /** User address (defaults to current signer) */
+  userAddress?: string;
+}
+
+/**
+ * Event emitted when capability is created
+ */
+export interface MemoryCapCreatedEvent {
+  capId: string;
+  owner: string;
+  appId: string;
+  nonce: string;
+  createdAt: number;
+}
+
+/**
+ * Event emitted when capability is transferred
+ */
+export interface MemoryCapTransferredEvent {
+  capId: string;
+  from: string;
+  to: string;
+  appId: string;
+}
+
+/**
+ * Event emitted when capability is burned
+ */
+export interface MemoryCapBurnedEvent {
+  capId: string;
+  owner: string;
+  appId: string;
+}
+
+/**
+ * Options for computing SEAL key ID
+ */
+export interface ComputeKeyIdOptions {
+  /** Owner address */
+  owner: string;
+  /** Nonce from capability */
+  nonce: string;
+}
+
+/**
+ * Capability namespace for SimplePDWClient
+ * Provides methods for managing MemoryCap objects
+ */
+export interface CapabilityNamespace {
+  /**
+   * Create a new MemoryCap for an app context
+   * @param appId Application identifier
+   * @returns Created capability
+   */
+  create(appId: string): Promise<MemoryCap>;
+
+  /**
+   * Get an existing capability by app ID
+   * @param appId Application identifier
+   * @returns Capability or null if not found
+   */
+  get(appId: string): Promise<MemoryCap | null>;
+
+  /**
+   * Get or create a capability for an app context
+   * @param appId Application identifier
+   * @returns Existing or newly created capability
+   */
+  getOrCreate(appId: string): Promise<MemoryCap>;
+
+  /**
+   * List all capabilities owned by the user
+   * @param options Optional filter options
+   * @returns List of capabilities
+   */
+  list(options?: ListCapsOptions): Promise<MemoryCap[]>;
+
+  /**
+   * Transfer a capability to another address
+   * @param capId Capability object ID
+   * @param recipient Recipient address
+   */
+  transfer(capId: string, recipient: string): Promise<void>;
+
+  /**
+   * Burn (revoke) a capability
+   * @param capId Capability object ID
+   */
+  burn(capId: string): Promise<void>;
+
+  /**
+   * Compute SEAL key ID for a capability
+   * @param cap Capability object
+   * @returns Key ID bytes as hex string
+   */
+  computeKeyId(cap: MemoryCap): string;
+}
+
+/**
+ * Context namespace for SimplePDWClient
+ * Higher-level abstraction over capabilities
+ */
+export interface ContextNamespace {
+  /**
+   * Create a new context (creates MemoryCap)
+   * @param appId Application identifier
+   * @returns Created capability
+   */
+  create(appId: string): Promise<MemoryCap>;
+
+  /**
+   * Get context by app ID
+   * @param appId Application identifier
+   * @returns Capability or null
+   */
+  get(appId: string): Promise<MemoryCap | null>;
+
+  /**
+   * Get or create context
+   * @param appId Application identifier
+   * @returns Existing or new capability
+   */
+  getOrCreate(appId: string): Promise<MemoryCap>;
+
+  /**
+   * List all contexts for user
+   * @returns List of capabilities
+   */
+  list(): Promise<MemoryCap[]>;
+
+  /**
+   * Delete a context (burns capability)
+   * @param appId Application identifier
+   */
+  delete(appId: string): Promise<void>;
+
+  /**
+   * Transfer context to another user
+   * @param appId Application identifier
+   * @param recipient Recipient address
+   */
+  transfer(appId: string, recipient: string): Promise<void>;
+}
+
+/**
+ * Wallet namespace for SimplePDWClient
+ * Simplified wallet operations (no HD wallet complexity)
+ */
+export interface WalletNamespace {
+  /**
+   * Get current wallet address
+   * @returns Wallet address
+   */
+  getAddress(): Promise<string>;
+
+  /**
+   * Check if wallet is connected/ready
+   * @returns Connection status
+   */
+  isConnected(): Promise<boolean>;
+
+  /**
+   * Get all owned objects of a specific type
+   * @param structType Move struct type
+   * @returns List of objects
+   */
+  getOwnedObjects<T>(structType: string): Promise<T[]>;
+}
+
+/**
+ * Memory creation options with capability
+ */
+export interface CreateMemoryWithCapOptions {
+  /** Capability to use for access control */
+  cap: MemoryCap;
+  /** Memory content */
+  content: string;
+  /** Memory category */
+  category: string;
+  /** Optional topic */
+  topic?: string;
+  /** Importance level 1-10 */
+  importance?: number;
+  /** Custom metadata */
+  customMetadata?: Record<string, string>;
+}
+
+/**
+ * Memory query options with context filtering
+ */
+export interface QueryMemoriesOptions {
+  /** User address */
+  userAddress: string;
+  /** Filter by app context (app_id) */
+  appId?: string;
+  /** Filter by category */
+  category?: string;
+  /** Maximum results */
+  limit?: number;
+}