@bananalink-sdk/protocol 1.2.7

package/dist/validators-export.d.cts

@@ -0,0 +1,37 @@
+declare function isValidAddress(address: unknown): address is string;
+declare function isValidUrl(url: unknown): url is string;
+declare function isValidTimestamp(timestamp: unknown): timestamp is string;
+declare function isValidChainId(chainId: unknown): chainId is number;
+declare function isValidNonce(nonce: unknown): nonce is string;
+declare function isValidSessionId(sessionId: unknown): sessionId is string;
+declare function isValidBase64(str: unknown): str is string;
+declare function isValidHex(hex: unknown): hex is string;
+interface ValidationResult<T = unknown> {
+    valid: boolean;
+    error?: string;
+    data?: T;
+}
+declare function isValidMessageType(type: unknown): type is 'auth' | 'tx' | 'sign';
+declare function isValidEncryptionAlgorithm(algo: unknown): algo is 'AES-GCM' | 'plaintext';
+declare function isValidDomain(domain: unknown): domain is string;
+declare function isValidPublicKey(publicKey: unknown): publicKey is string;
+interface EncryptedPayload {
+    iv: string;
+    ciphertext: string;
+    mac: string;
+}
+declare function isValidEncryptedPayload(payload: unknown): payload is EncryptedPayload;
+declare function createValidationResult<T = unknown>(valid: boolean, data?: T, error?: string): ValidationResult<T>;
+declare function hasRequiredFields<T extends object>(obj: unknown, fields: (keyof T)[]): obj is T;
+interface SIWEMessage {
+    domain: string;
+    address: string;
+    uri: string;
+    version: string;
+    chainId: number;
+    nonce: string;
+    issuedAt: string;
+}
+declare function isValidSIWEMessage(message: unknown): message is SIWEMessage;
+
+export { type EncryptedPayload, type SIWEMessage, type ValidationResult, createValidationResult, hasRequiredFields, isValidAddress, isValidBase64, isValidChainId, isValidDomain, isValidEncryptedPayload, isValidEncryptionAlgorithm, isValidHex, isValidMessageType, isValidNonce, isValidPublicKey, isValidSIWEMessage, isValidSessionId, isValidTimestamp, isValidUrl };

package/dist/validators-export.d.ts

@@ -0,0 +1,37 @@
+declare function isValidAddress(address: unknown): address is string;
+declare function isValidUrl(url: unknown): url is string;
+declare function isValidTimestamp(timestamp: unknown): timestamp is string;
+declare function isValidChainId(chainId: unknown): chainId is number;
+declare function isValidNonce(nonce: unknown): nonce is string;
+declare function isValidSessionId(sessionId: unknown): sessionId is string;
+declare function isValidBase64(str: unknown): str is string;
+declare function isValidHex(hex: unknown): hex is string;
+interface ValidationResult<T = unknown> {
+    valid: boolean;
+    error?: string;
+    data?: T;
+}
+declare function isValidMessageType(type: unknown): type is 'auth' | 'tx' | 'sign';
+declare function isValidEncryptionAlgorithm(algo: unknown): algo is 'AES-GCM' | 'plaintext';
+declare function isValidDomain(domain: unknown): domain is string;
+declare function isValidPublicKey(publicKey: unknown): publicKey is string;
+interface EncryptedPayload {
+    iv: string;
+    ciphertext: string;
+    mac: string;
+}
+declare function isValidEncryptedPayload(payload: unknown): payload is EncryptedPayload;
+declare function createValidationResult<T = unknown>(valid: boolean, data?: T, error?: string): ValidationResult<T>;
+declare function hasRequiredFields<T extends object>(obj: unknown, fields: (keyof T)[]): obj is T;
+interface SIWEMessage {
+    domain: string;
+    address: string;
+    uri: string;
+    version: string;
+    chainId: number;
+    nonce: string;
+    issuedAt: string;
+}
+declare function isValidSIWEMessage(message: unknown): message is SIWEMessage;
+
+export { type EncryptedPayload, type SIWEMessage, type ValidationResult, createValidationResult, hasRequiredFields, isValidAddress, isValidBase64, isValidChainId, isValidDomain, isValidEncryptedPayload, isValidEncryptionAlgorithm, isValidHex, isValidMessageType, isValidNonce, isValidPublicKey, isValidSIWEMessage, isValidSessionId, isValidTimestamp, isValidUrl };

package/dist/validators-export.js

@@ -0,0 +1,4 @@
+export { createValidationResult, hasRequiredFields, isValidAddress, isValidBase64, isValidChainId, isValidDomain, isValidEncryptedPayload, isValidEncryptionAlgorithm, isValidHex, isValidMessageType, isValidNonce, isValidPublicKey, isValidSIWEMessage, isValidSessionId, isValidTimestamp, isValidUrl } from './chunk-JXHV66Q4.js';
+import './chunk-WCQVDF3K.js';
+//# sourceMappingURL=validators-export.js.map
+//# sourceMappingURL=validators-export.js.map

package/dist/validators-export.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"validators-export.js"}

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@bananalink-sdk/protocol",
+  "version": "1.2.7",
+  "description": "Core protocol definitions for BananaLink. Provides TypeScript types, Zod validation schemas, cryptographic utilities, and shared constants for wallet connections.",
+  "type": "module",
+  "keywords": [
+    "bananalink",
+    "protocol",
+    "types",
+    "schemas",
+    "validation",
+    "cryptography",
+    "web3"
+  ],
+  "bugs": {
+    "url": "https://github.com/bananalink/bananalink/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bananalink/bananalink.git",
+    "directory": "packages/protocol"
+  },
+  "license": "ISC",
+  "author": "BananaLink Team <team@banana.link>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.js",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./schemas": {
+      "types": "./dist/schemas-export.d.ts",
+      "react-native": "./dist/schemas-export.js",
+      "import": "./dist/schemas-export.js",
+      "require": "./dist/schemas-export.cjs"
+    },
+    "./validators": {
+      "types": "./dist/validators-export.d.ts",
+      "react-native": "./dist/validators-export.js",
+      "import": "./dist/validators-export.js",
+      "require": "./dist/validators-export.cjs"
+    },
+    "./validation": {
+      "types": "./dist/validation-export.d.ts",
+      "react-native": "./dist/validation-export.js",
+      "import": "./dist/validation-export.js",
+      "require": "./dist/validation-export.cjs"
+    },
+    "./siwe": {
+      "types": "./dist/siwe-export.d.ts",
+      "react-native": "./dist/siwe-export.js",
+      "import": "./dist/siwe-export.js",
+      "require": "./dist/siwe-export.cjs"
+    },
+    "./crypto": {
+      "types": "./dist/crypto-export.d.ts",
+      "react-native": "./dist/crypto-export.js",
+      "import": "./dist/crypto-export.js",
+      "require": "./dist/crypto-export.cjs"
+    },
+    "./crypto/provider/webcrypto": {
+      "types": "./dist/crypto/providers/webcrypto-provider.d.ts",
+      "react-native": "./dist/crypto/providers/webcrypto-provider.js",
+      "import": "./dist/crypto/providers/webcrypto-provider.js",
+      "require": "./dist/crypto/providers/webcrypto-provider.cjs"
+    },
+    "./crypto/provider/node": {
+      "types": "./dist/crypto/providers/node-provider.d.ts",
+      "react-native": "./dist/crypto/providers/node-provider.js",
+      "import": "./dist/crypto/providers/node-provider.js",
+      "require": "./dist/crypto/providers/node-provider.cjs"
+    },
+    "./crypto/provider/noble": {
+      "types": "./dist/crypto/providers/noble-provider.d.ts",
+      "react-native": "./dist/crypto/providers/noble-provider.js",
+      "import": "./dist/crypto/providers/noble-provider.js",
+      "require": "./dist/crypto/providers/noble-provider.cjs"
+    },
+    "./crypto/provider/quickcrypto": {
+      "types": "./dist/crypto/providers/quickcrypto-provider.d.ts",
+      "react-native": "./dist/crypto/providers/quickcrypto-provider.js",
+      "import": "./dist/crypto/providers/quickcrypto-provider.js",
+      "require": "./dist/crypto/providers/quickcrypto-provider.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "react-native": "./dist/testing.js",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist node_modules",
+    "dev": "tsup --watch",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bananalink-sdk/logger": "workspace:*",
+    "@noble/ciphers": "^2.0.0",
+    "@noble/curves": "^2.0.0",
+    "@noble/hashes": "^2.0.0",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@bananalink-sdk/eslint-config": "workspace:*",
+    "@bananalink-sdk/typescript-config": "workspace:*",
+    "@types/node": "^24.1.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.29.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "react-native-quick-crypto": "^0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-quick-crypto": {
+      "optional": true
+    }
+  },
+  "packageManager": "pnpm@10.15.1"
+}

package/src/constants/index.ts

@@ -0,0 +1,205 @@
+/**
+ * Constants for the BananaLink protocol
+ * Contains protocol version, URLs, timeouts, and other configuration values
+ */
+
+// Protocol version and identification
+export const PROTOCOL_VERSION = 1;
+export const PACKAGE_NAME = '@bananalink-sdk/protocol';
+export const DEEPLINK_SCHEME = 'bananalink';
+
+// Default relay server configuration
+export const DEFAULT_RELAY_URL = 'wss://relay.banana.link/v1';
+
+// FrutiLink emoji set (16 fruits for 4 bits each)
+export const FRUITS = [
+  '🍌', '🍎', '🍊', '🍇', '🍓', '🍑', '🍒', '🍉',
+  '🥝', '🍍', '🥭', '🥥', '🫐', '🍈', '🍋', '🥑'
+] as const;
+
+// Timeout configurations (in milliseconds)
+export const DEFAULT_TIMEOUTS = {
+  sessionTimeout: 24 * 60 * 60 * 1000, // 24 hours
+  requestTimeout: 5 * 60 * 1000,       // 5 minutes
+  connectionTimeout: 30 * 1000,        // 30 seconds
+  qrCodeTimeout: 2 * 60 * 1000,        // 2 minutes
+} as const;
+
+// Protocol v2.0 specific timeouts (in milliseconds)
+// Based on PROTOCOL.md specification
+export const PROTOCOL_V2_TIMEOUTS = {
+  sessionCreation: 5 * 1000,           // 5 seconds - API Gateway response
+  claimSession: 10 * 1000,             // 10 seconds - Wallet claims ownership
+  prefetchMetadata: 5 * 1000,          // 5 seconds - Fetch dApp info
+  userApproval: 5 * 60 * 1000,         // 5 minutes - User decision time
+  authentication: 30 * 1000,           // 30 seconds - Sign and send
+  sessionTTL: 10800 * 1000,            // 10800 seconds (3 hours) - Max session lifetime
+  reconnectionWindow: 10800 * 1000,    // 10800 seconds (3 hours) - Same as session TTL
+  messageQueueRetention: 10800 * 1000, // 10800 seconds (3 hours) - Matches session TTL
+  websocketHeartbeat: 30 * 1000,       // 30 seconds - Keep-alive ping
+  gracefulCloseTimeout: 5 * 1000,      // 5 seconds - close_session ack wait
+  // Post-authentication operation timeouts (v2.1+)
+  signMessage: 60 * 1000,              // 60 seconds - personal_sign operation
+  signTypedData: 90 * 1000,            // 90 seconds - eth_signTypedData_v4 operation
+  signTransaction: 120 * 1000,         // 120 seconds - Transaction signing
+} as const;
+
+// Message queue configuration
+export const MESSAGE_QUEUE_CONFIG = {
+  maxQueueSize: 100,                   // Maximum messages per direction
+  retentionTime: 10800 * 1000,         // 10800 seconds (3 hours) - Matches session TTL
+  overflowStrategy: 'drop_oldest',     // Drop oldest messages when queue is full
+} as const;
+
+// Security limits and constraints
+export const SECURITY_LIMITS = {
+  maxConcurrentSessions: 5,
+  maxSessionAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+  minNonceLength: 8,
+  maxMessageSize: 64 * 1024, // 64KB
+  maxResourcesCount: 10,
+  rateLimit: {
+    requestsPerMinute: 60,
+    sessionsPerHour: 100,
+  },
+} as const;
+
+// Cryptographic constants
+export const CRYPTO_CONSTANTS = {
+  keyLength: 256,           // AES-256
+  ivLength: 12,            // GCM IV length
+  tagLength: 16,           // GCM tag length
+  curve: 'P-256',          // ECDH curve
+  algorithm: 'AES-GCM',    // Encryption algorithm
+  hashAlgorithm: 'SHA-256', // Hash algorithm
+} as const;
+
+// Message format constants
+export const MESSAGE_FORMAT = {
+  version: '1',
+  encoding: 'utf8',
+  lineBreak: '\n',
+  resourcePrefix: '- ',
+} as const;
+
+// WebSocket message types
+export const WS_MESSAGE_TYPES = {
+  subscribe: 'sub',
+  publish: 'pub',
+  acknowledge: 'ack',
+  error: 'error',
+} as const;
+
+// HTTP endpoints for fallback
+export const HTTP_ENDPOINTS = {
+  messages: '/v1/messages',
+  session: '/v1/session',
+  health: '/v1/health',
+} as const;
+
+// Error messages (organized hierarchically)
+export const ERROR_MESSAGES = {
+  // Session errors
+  SESSION_EXPIRED: 'Session has expired',
+  SESSION_NOT_FOUND: 'Session ID invalid or expired',
+  SESSION_ALREADY_CLAIMED: 'Session already claimed by another wallet',
+  INVALID_SESSION_CLAIM: 'Wallet does not own this session',
+  INVALID_CLIENT_CLAIM: 'Client session claim does not match',
+  SESSION_TOKEN_EXPIRED: 'Session token TTL exceeded',
+  SESSION_CLOSED: 'Session has been closed',
+
+  // Encryption errors
+  ENCRYPTION_FAILED: 'Message encryption failed',
+  DECRYPTION_FAILED: 'Cannot decrypt message',
+  INVALID_SIGNATURE: 'Invalid signature',
+
+  // Network errors
+  NETWORK_ERROR: 'Network connection error',
+  RELAY_ERROR: 'Internal relay server error',
+  MESSAGE_QUEUE_FULL: 'Too many queued messages (>100)',
+  RATE_LIMIT_EXCEEDED: 'Rate limit exceeded',
+  ORIGIN_MISMATCH: 'Origin verification failed',
+
+  // Request lifecycle errors (v2.1+)
+  REQUEST_PENDING: 'Another signing request is already pending',
+  REQUEST_NOT_FOUND: 'Request ID not found or already processed',
+  REQUEST_EXPIRED: 'Request expired before completion',
+  REQUEST_INVALID: 'Request data is invalid or malformed',
+  REQUEST_TIMEOUT: 'Request timed out waiting for wallet response',
+
+  // Operation-specific errors (v2.1+)
+  SIGNING_FAILED: 'Cryptographic signing operation failed',
+  SIGNING_REJECTED: 'User rejected the signing request',
+  TRANSACTION_INVALID: 'Transaction parameters validation failed',
+  CHAIN_MISMATCH: 'Requested chain ID does not match wallet chain',
+} as const;
+
+// QR code configuration
+export const QR_CONFIG = {
+  size: 256,
+  margin: 4,
+  errorCorrectionLevel: 'M',
+  type: 'image/png',
+} as const;
+
+// Deep link configuration
+export const DEEP_LINK_CONFIG = {
+  scheme: DEEPLINK_SCHEME,
+  host: 'connect',
+  universal: 'https://bananalink.app',
+} as const;
+
+// Network configuration
+export const NETWORK_CONFIG = {
+  SUPPORTED_CHAINS: [
+    1,     // Ethereum Mainnet
+    5,     // Goerli Testnet
+    137,   // Polygon Mainnet
+    80001, // Polygon Mumbai Testnet
+    42161, // Arbitrum One
+    421613, // Arbitrum Goerli
+    10,    // Optimism
+    420,   // Optimism Goerli
+  ],
+  DEFAULT_CHAIN_ID: 1,
+  CHAIN_NAMES: {
+    1: 'Ethereum Mainnet',
+    5: 'Goerli Testnet',
+    137: 'Polygon Mainnet',
+    80001: 'Polygon Mumbai',
+    42161: 'Arbitrum One',
+    421613: 'Arbitrum Goerli',
+    10: 'Optimism',
+    420: 'Optimism Goerli',
+  } as const,
+} as const;
+
+// Development configuration
+export const DEV_CONFIG = {
+  logLevel: 'debug',
+  enableMocks: false,
+  skipValidation: false,
+  allowLocalhost: true,
+} as const;
+
+// Export all constants as a single object for convenience
+export const BANANALINK_CONSTANTS = {
+  PROTOCOL_VERSION,
+  PACKAGE_NAME,
+  DEEPLINK_SCHEME,
+  DEFAULT_RELAY_URL,
+  FRUITS,
+  DEFAULT_TIMEOUTS,
+  PROTOCOL_V2_TIMEOUTS,
+  MESSAGE_QUEUE_CONFIG,
+  SECURITY_LIMITS,
+  CRYPTO_CONSTANTS,
+  MESSAGE_FORMAT,
+  WS_MESSAGE_TYPES,
+  HTTP_ENDPOINTS,
+  ERROR_MESSAGES,
+  QR_CONFIG,
+  DEEP_LINK_CONFIG,
+  NETWORK_CONFIG,
+  DEV_CONFIG,
+} as const;

package/src/crypto/context.ts

@@ -0,0 +1,228 @@
+/**
+ * CryptoContext - Singleton manager for the active crypto provider
+ *
+ * Provides a global context for crypto operations while maintaining
+ * the ability to use custom providers when needed.
+ *
+ * @example
+ * // Automatic initialization with best available provider
+ * const bytes = randomBytes(32);
+ *
+ * @example
+ * // Explicit provider configuration
+ * CryptoContext.initialize({ type: 'noble' });
+ * const bytes = randomBytes(32);
+ *
+ * @example
+ * // Custom provider instance
+ * const provider = new NobleCryptoProvider();
+ * CryptoContext.setProvider(provider);
+ */
+
+import type { Logger } from '@bananalink-sdk/logger';
+import type { CryptoProvider, CryptoProviderType } from '../types/crypto-provider';
+import { createCryptoProvider, getRegisteredCryptoProviders } from './providers';
+import { ComplianceCryptoProvider } from './providers/compliance-provider';
+import type { ComplianceConfig } from './providers/compliance-provider';
+import { CryptoProviderUnavailableError } from './errors';
+import { detectPlatform } from './utils';
+
+export interface CryptoContextConfig {
+  /** Provider type to use (auto-detects if not specified) */
+  type?: CryptoProviderType;
+  /** Strict mode - throw if preferred provider unavailable (default: false) */
+  strict?: boolean;
+  /** Compliance configuration (wraps provider if enabled) */
+  compliance?: ComplianceConfig;
+  /** Logger instance for debug output */
+  logger?: Logger;
+}
+
+/**
+ * Singleton context for managing the active crypto provider
+ *
+ * Design rationale:
+ * - Provides convenient global access to crypto operations
+ * - Maintains lazy initialization for tree-shaking
+ * - Allows explicit provider configuration when needed
+ * - Supports both automatic and manual provider selection
+ */
+class CryptoContextManager {
+  private provider: CryptoProvider | null = null;
+  private config: CryptoContextConfig | null = null;
+  private initialized = false;
+  private initializing = false;
+
+  /**
+   * Initialize the crypto context with specific configuration
+   *
+   * @param config - Provider configuration options
+   * @throws Error if already initialized (call reset() first)
+   * @throws CryptoProviderUnavailableError if strict mode enabled and provider unavailable
+   */
+  initialize(config: CryptoContextConfig = {}): void {
+    if (this.initialized && this.provider) {
+      throw new Error(
+        'CryptoContext already initialized. Call CryptoContext.reset() first to reconfigure.'
+      );
+    }
+
+    // Strict mode validation - check if provider is registered
+    if (config.strict && config.type) {
+      const availableProviders = getRegisteredCryptoProviders();
+      if (!availableProviders.includes(config.type)) {
+        const platform = detectPlatform();
+        const recommendations: string[] = [
+          `Import the provider: import '@bananalink-sdk/protocol/crypto/provider/${config.type}'`,
+          'Ensure the provider package is installed',
+        ];
+
+        // Add platform-specific recommendations
+        if (config.type === 'quickcrypto' && !platform.isReactNative) {
+          recommendations.push('QuickCrypto requires React Native environment');
+          if (platform.isNode) {
+            recommendations.push("Try 'node' provider for Node.js");
+          } else if (platform.isBrowser) {
+            recommendations.push("Try 'webcrypto' provider for browsers");
+          }
+        }
+
+        // Add universal fallback recommendation
+        if (availableProviders.includes('noble')) {
+          recommendations.push("'noble' provider works in all environments as a fallback");
+        }
+
+        throw new CryptoProviderUnavailableError(
+          `Strict mode: Crypto provider '${config.type}' is not registered. Did you forget to import it?`,
+          {
+            requestedProvider: config.type,
+            availableProviders,
+            platform,
+            recommendations,
+          }
+        );
+      }
+    }
+
+    this.config = config;
+    this.provider = this.createProvider(config);
+    this.initialized = true;
+  }
+
+  /**
+   * Get the active crypto provider
+   * Automatically initializes with default config if not already initialized
+   *
+   * @returns The active crypto provider instance
+   * @throws Error if called concurrently during initialization
+   *
+   * @remarks
+   * This method performs lazy initialization on first call. It is NOT safe to call
+   * concurrently from multiple contexts before initialization completes (e.g., from
+   * Worker threads or Promise.all). For concurrent access scenarios, explicitly call
+   * initialize() first to ensure the provider is ready before concurrent operations begin.
+   *
+   * @example
+   * ```typescript
+   * // Safe: Single-threaded lazy initialization
+   * const provider = CryptoContext.getProvider();
+   *
+   * // Safe: Pre-initialize for concurrent access
+   * CryptoContext.initialize({ type: 'noble' });
+   * await Promise.all([
+   *   operation1(CryptoContext.getProvider()),
+   *   operation2(CryptoContext.getProvider())
+   * ]);
+   *
+   * // Unsafe: Concurrent calls during lazy initialization
+   * await Promise.all([
+   *   operation1(CryptoContext.getProvider()), // May throw if not initialized yet
+   *   operation2(CryptoContext.getProvider())
+   * ]);
+   * ```
+   */
+  getProvider(): CryptoProvider {
+    // Check if already initialized
+    if (this.provider) {
+      return this.provider;
+    }
+
+    // Prevent race condition - if already initializing, throw error
+    if (this.initializing) {
+      throw new Error(
+        'CryptoContext initialization in progress. Avoid concurrent calls to getProvider() during initialization.'
+      );
+    }
+
+    // Lazy initialization with defaults
+    this.initializing = true;
+    try {
+      this.initialize();
+      // After initialize(), provider is guaranteed to be set
+      if (!this.provider) {
+        throw new Error('CryptoContext initialization failed: provider is null');
+      }
+      return this.provider;
+    } finally {
+      this.initializing = false;
+    }
+  }
+
+  /**
+   * Set a custom provider instance
+   * Useful for testing or advanced use cases
+   *
+   * @param provider - Custom provider instance
+   */
+  setProvider(provider: CryptoProvider): void {
+    this.provider = provider;
+    this.initialized = true;
+  }
+
+  /**
+   * Check if context has been explicitly initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): CryptoContextConfig | null {
+    return this.config;
+  }
+
+  /**
+   * Reset the context (for testing or reconfiguration)
+   */
+  reset(): void {
+    this.provider = null;
+    this.config = null;
+    this.initialized = false;
+    this.initializing = false;
+  }
+
+  /**
+   * Create a provider instance from configuration
+   */
+  private createProvider(config: CryptoContextConfig): CryptoProvider {
+    const baseProvider = createCryptoProvider(config.type, config.logger, config.strict);
+
+    if (config.compliance?.enabled) {
+      return new ComplianceCryptoProvider(baseProvider, config.compliance);
+    }
+
+    return baseProvider;
+  }
+
+}
+
+/**
+ * Global singleton instance
+ *
+ * Usage:
+ * - Most code should use utility functions (randomBytes, generateNonce)
+ * - Advanced use cases can access CryptoContext directly
+ */
+export const CryptoContext = new CryptoContextManager();