@bananalink-sdk/protocol 1.2.7

package/README.md

@@ -0,0 +1,604 @@
+# @bananalink-sdk/protocol
+
+The core protocol package for BananaLink, containing all TypeScript types, Zod validation schemas, and constants for the dApp-to-wallet communication protocol.
+
+## Documentation
+
+- **[Protocol Specification](./docs/PROTOCOL.md)** - Complete protocol specification with message types, flows, and security model
+- **[Implementation Guide](./docs/IMPLEMENTATION.md)** - SDK integration examples, wallet integration patterns, and best practices
+
+## Table of Contents
+
+- [Core Interfaces](#core-interfaces)
+  - [SIWE Fields](#siwe-fields)
+  - [BananaLink Message](#bananalink-message)
+  - [Transaction Payload](#transaction-payload)
+  - [Sign Payload](#sign-payload)
+  - [BananaLink Response](#bananalink-response)
+- [Metadata & Configuration](#metadata--configuration)
+  - [DApp Metadata](#dapp-metadata)
+  - [Session Config](#session-config)
+  - [Session Options](#session-options)
+  - [Security Policy](#security-policy)
+- [Discovery Types](#discovery-types)
+  - [QR Payload](#qr-payload)
+  - [Display Info](#display-info)
+  - [Relay Message](#relay-message)
+  - [Encrypted Payload](#encrypted-payload)
+- [Authentication Types](#authentication-types)
+  - [Session Info](#session-info)
+  - [Origin Proof](#origin-proof)
+- [Cryptographic Types](#cryptographic-types)
+  - [Crypto Payload](#crypto-payload)
+  - [Key Exchange](#key-exchange)
+  - [Encryption](#encryption)
+  - [Public Key JWK](#public-key-jwk)
+  - [Key Derivation](#key-derivation)
+- [Error Types](#error-types)
+  - [BananaLink Error](#bananalink-error)
+- [Constants](#constants)
+- [Validation Schemas](#validation-schemas)
+
+---
+
+## Core Interfaces
+
+### SIWE Fields
+
+Based on ERC-4361 Sign-In with Ethereum standard:
+
+```typescript
+interface SIWEFields {
+  scheme?: string;          // URI scheme of the origin (e.g., "https")
+  domain: string;           // Domain requesting the signing (e.g., "mydapp.com")
+  address: string;          // Ethereum address performing the signing
+  statement?: string;       // Human-readable assertion for user to sign
+  uri: string;             // Resource URI subject of the signing
+  version: string;         // SIWE Message version (must be "1")
+  chainId: number;         // EIP-155 Chain ID (e.g., 1 for Ethereum mainnet)
+  nonce: string;           // Random string for replay protection (min 8 chars)
+  issuedAt: string;        // ISO 8601 datetime when message was generated
+  expirationTime?: string; // ISO 8601 datetime when message expires
+  notBefore?: string;      // ISO 8601 datetime when message becomes valid
+  requestId?: string;      // System-specific identifier for the request
+  resources?: string[];    // List of information/references to resolve
+}
+```
+
+### BananaLink Message
+
+Main message interface extending SIWE with BananaLink protocol extensions:
+
+```typescript
+interface BananaLinkMessage extends SIWEFields {
+  type: 'auth' | 'tx' | 'sign';                    // Type of BananaLink request
+  sessionId: string;                               // Unique session identifier
+  payload?: TransactionPayload | SignPayload;     // Request-specific payload
+}
+```
+
+### Transaction Payload
+
+For transaction signing requests:
+
+```typescript
+interface TransactionPayload {
+  to: string;                      // Recipient address
+  value?: string;                  // Value in wei as string
+  data?: string;                   // Transaction data (hex string)
+  gas?: string;                    // Gas limit as string
+  gasPrice?: string;               // Gas price for legacy transactions
+  maxFeePerGas?: string;          // Max fee per gas (EIP-1559)
+  maxPriorityFeePerGas?: string;  // Max priority fee per gas (EIP-1559)
+}
+```
+
+### Sign Payload
+
+For message signing requests:
+
+```typescript
+interface SignPayload {
+  message: string;                 // Message to sign
+  encoding?: 'utf8' | 'hex';      // Encoding format (default: 'utf8')
+}
+```
+
+### BananaLink Response
+
+Response format for all requests:
+
+```typescript
+interface BananaLinkResponse {
+  success: boolean;    // Whether the request was successful
+  data?: any;         // Response data (signature, tx hash, etc.)
+  error?: string;     // Error message if unsuccessful
+  requestId?: string; // Request ID for correlation
+}
+```
+
+---
+
+## Metadata & Configuration
+
+### DApp Metadata
+
+Metadata for dApp registration and discovery:
+
+```typescript
+interface DAppMetadata {
+  name: string;          // Name of the dApp
+  description?: string;  // Description of the dApp
+  url: string;          // URL of the dApp
+  icons?: string[];     // Array of icon URLs
+}
+```
+
+### Session Config
+
+Session-specific configuration (separate from dApp metadata):
+
+```typescript
+interface SessionConfig {
+  returnUrl?: string;                      // URL to redirect after completion
+  sessionName?: string;                    // Human-readable session identifier
+  expiresAt?: string;                     // Session expiration (ISO 8601)
+  customData?: Record<string, unknown>;   // Custom session data
+}
+```
+
+### Session Options
+
+Options for creating new sessions:
+
+```typescript
+interface SessionOptions {
+  config?: SessionConfig;                  // Session configuration
+  securityPolicy?: Partial<SecurityPolicy>; // Security policy overrides
+}
+```
+
+### Security Policy
+
+Security configuration for sessions:
+
+```typescript
+interface SecurityPolicy {
+  sessionTimeout: number;           // Session timeout in milliseconds
+  requestTimeout: number;           // Request timeout in milliseconds
+  maxConcurrentSessions: number;    // Max concurrent sessions allowed
+  requireOriginProof: boolean;      // Require domain ownership proof
+  allowedDomains?: string[];        // Allowed domains whitelist
+  blockedDomains?: string[];        // Blocked domains blacklist
+}
+```
+
+---
+
+## Discovery Types
+
+### QR Payload
+
+Data structure encoded in QR codes for wallet discovery:
+
+```typescript
+interface QRPayload {
+  version: number;                                 // Protocol version
+  sessionId: string;                              // Session identifier
+  publicKey: string;                              // Public key for ECDHE
+  dappInfo: Pick<DAppMetadata, 'name' | 'url'>;  // Essential dApp info
+  sessionConfig?: SessionConfig;                   // Session configuration
+}
+```
+
+### Display Info
+
+Information for displaying connection options to users:
+
+```typescript
+interface DisplayInfo {
+  qrCode: string;     // QR code data URL (base64 PNG)
+  frutiLink: string;  // FrutiLink emoji sequence
+  deepLink: string;   // Deep link URL for mobile apps
+}
+```
+
+### Relay Message
+
+Message format for relay server communication:
+
+```typescript
+interface RelayMessage {
+  topic: string;                    // Session ID used as topic
+  type: 'pub' | 'sub' | 'ack' | 'error'; // Message type
+  payload?: EncryptedPayload;       // Encrypted payload (optional)
+  id: string;                       // Message ID for acknowledgment
+}
+```
+
+### Encrypted Payload
+
+Encrypted message payload for secure communication:
+
+```typescript
+interface EncryptedPayload {
+  iv: string;         // Base64 encoded initialization vector
+  ciphertext: string; // Base64 encoded ciphertext
+  mac: string;        // Base64 encoded HMAC for integrity
+}
+```
+
+---
+
+## Authentication Types
+
+### Session Info
+
+Complete session information:
+
+```typescript
+interface SessionInfo {
+  sessionId: string;                              // Session identifier
+  state: 'pending' | 'connected' | 'disconnected' | 'expired' | 'error'; // Current state
+  address?: string;                               // Connected wallet address
+  dappId: string;                                // DApp identifier
+  dappInfo: Pick<DAppMetadata, 'name' | 'url'>;  // Essential dApp info
+  sessionConfig?: SessionConfig;                   // Session configuration
+  createdAt: string;                              // Creation timestamp (ISO 8601)
+  lastActivity: string;                           // Last activity timestamp (ISO 8601)
+  expiresAt?: string;                            // Expiration timestamp (ISO 8601)
+}
+```
+
+### Origin Proof
+
+Proof of domain ownership for security verification:
+
+```typescript
+interface OriginProof {
+  domain: string;     // Domain asserting ownership
+  timestamp: number;  // Timestamp of the proof
+  signature: string;  // Signature proving domain ownership
+}
+```
+
+---
+
+## Cryptographic Types
+
+### Crypto Payload
+
+Complete cryptographic payload specification:
+
+```typescript
+interface CryptoPayload {
+  version: '1.0';                                    // Schema version
+  keyExchange?: KeyExchange;                         // Key exchange algorithm
+  encryption: Encryption;                            // Encryption specification
+  publicKey?: PublicKeyJWK;                         // Public key in JWK format
+  parameters: CryptoParameters;                      // Algorithm parameters
+  derivation?: KeyDerivation;                       // Key derivation spec
+}
+```
+
+### Key Exchange
+
+ECDH key exchange specification:
+
+```typescript
+interface KeyExchange {
+  algorithm: 'ECDH';      // Elliptic Curve Diffie-Hellman
+  namedCurve: 'P-256';   // NIST P-256 curve (secp256r1)
+}
+```
+
+### Encryption
+
+Encryption algorithm specification:
+
+```typescript
+interface Encryption {
+  algorithm: 'AES-GCM' | 'plaintext'; // Encryption algorithm
+  keyLength?: 256;                     // AES key length in bits
+  tagLength?: 128;                     // GCM authentication tag length
+}
+```
+
+### Public Key JWK
+
+Public key in JSON Web Key format for ECDH:
+
+```typescript
+interface PublicKeyJWK {
+  kty: 'EC';              // Key type: Elliptic Curve
+  crv: 'P-256';          // Curve name
+  x: string;             // X coordinate (base64url)
+  y: string;             // Y coordinate (base64url)
+  use: 'enc';            // Intended use: encryption
+  key_ops: ['deriveKey']; // Permitted operations
+}
+```
+
+### Key Derivation
+
+HKDF key derivation specification:
+
+```typescript
+interface KeyDerivation {
+  algorithm: 'HKDF';                  // HMAC-based Key Derivation Function
+  hash: 'SHA-256';                   // Hash function for HKDF
+  info: 'message-exchange-v1';       // Application context info
+  salt: string;                      // Random salt (base64)
+}
+```
+
+---
+
+## Error Types
+
+### BananaLink Error
+
+Standardized error format:
+
+```typescript
+interface BananaLinkError {
+  code: BananaLinkErrorCode;  // Standardized error code
+  message: string;            // Human-readable error message
+  details?: any;             // Additional error details
+}
+
+type BananaLinkErrorCode = 
+  | 'USER_REJECTED'        // User rejected the request
+  | 'INVALID_REQUEST'      // Request format is invalid
+  | 'SESSION_EXPIRED'      // Session has expired
+  | 'NETWORK_ERROR'        // Network connection error
+  | 'UNSUPPORTED_METHOD'   // Method not supported
+  | 'INVALID_SIGNATURE'    // Signature validation failed
+  | 'ORIGIN_MISMATCH'      // Origin verification failed
+  | 'RATE_LIMITED';        // Rate limit exceeded
+```
+
+---
+
+## Constants
+
+Key protocol constants are exported from `@bananalink-sdk/protocol/constants`:
+
+```typescript
+// Protocol identification
+PROTOCOL_VERSION: 1
+PACKAGE_NAME: '@bananalink-sdk/protocol'
+DEEPLINK_SCHEME: 'bananalink'
+
+// Timeouts (milliseconds)
+DEFAULT_TIMEOUTS: {
+  sessionTimeout: 86400000    // 24 hours
+  requestTimeout: 300000      // 5 minutes
+  connectionTimeout: 30000    // 30 seconds
+  qrCodeTimeout: 120000       // 2 minutes
+}
+
+// Security limits
+SECURITY_LIMITS: {
+  maxConcurrentSessions: 5
+  maxSessionAge: 604800000    // 7 days
+  minNonceLength: 8
+  maxMessageSize: 65536       // 64KB
+  maxResourcesCount: 10
+}
+
+// Cryptographic constants
+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
+}
+```
+
+---
+
+## Validation Schemas
+
+All types have corresponding Zod validation schemas for runtime validation:
+
+```typescript
+import { 
+  bananaLinkMessageSchema,
+  dAppMetadataSchema,
+  sessionConfigSchema,
+  sessionOptionsSchema,
+  securityPolicySchema,
+  transactionPayloadSchema,
+  signPayloadSchema
+} from '@bananalink-sdk/protocol/schemas';
+
+// Validate a BananaLink message
+const message = bananaLinkMessageSchema.parse(data);
+
+// Safe parsing (returns result object)
+const result = bananaLinkMessageSchema.safeParse(data);
+if (result.success) {
+  console.log('Valid message:', result.data);
+} else {
+  console.error('Validation errors:', result.error.issues);
+}
+```
+
+### Validation Helpers
+
+```typescript
+import { validateMessage, safeValidateMessage } from '@bananalink-sdk/protocol/schemas';
+
+// Throws on validation error
+const validMessage = validateMessage(data);
+
+// Returns safe parse result
+const result = safeValidateMessage(data);
+```
+
+---
+
+## Usage
+
+```typescript
+import type { 
+  BananaLinkMessage,
+  DAppMetadata,
+  SessionConfig,
+  SessionOptions
+} from '@bananalink-sdk/protocol/types';
+
+import { 
+  bananaLinkMessageSchema,
+  sessionOptionsSchema
+} from '@bananalink-sdk/protocol/schemas';
+
+import { 
+  DEEPLINK_SCHEME,
+  DEFAULT_TIMEOUTS
+} from '@bananalink-sdk/protocol/constants';
+```
+
+---
+
+## Crypto Provider System
+
+The protocol package includes a pluggable cryptographic provider system with support for multiple implementations. Crypto providers must be **explicitly imported** to be available.
+
+### Available Providers
+
+- **`noble`** - Pure JavaScript implementation (universal fallback, works everywhere)
+- **`webcrypto`** - Browser Web Crypto API (fastest in browsers)
+- **`node`** - Node.js native crypto (fastest in Node.js)
+- **`quickcrypto`** - React Native optimized (for React Native environments)
+
+### Explicit Provider Import
+
+Providers use a registry pattern with side-effect imports. You must explicitly import each provider you want to use:
+
+```typescript
+// Import the crypto providers you need
+import '@bananalink-sdk/protocol/crypto/provider/noble';      // Always recommended as fallback
+import '@bananalink-sdk/protocol/crypto/provider/webcrypto';  // For browsers
+import '@bananalink-sdk/protocol/crypto/provider/node';       // For Node.js
+import '@bananalink-sdk/protocol/crypto/provider/quickcrypto'; // For React Native
+
+// Now the providers are registered and available
+import { createCryptoProvider } from '@bananalink-sdk/protocol/crypto';
+
+// Create a provider (will use the first available in priority order)
+const provider = createCryptoProvider();
+
+// Or specify a provider explicitly
+const nobleProvider = createCryptoProvider('noble');
+```
+
+### Why Explicit Imports?
+
+This design provides several benefits:
+
+1. **Tree Shaking** - Only bundle the providers you actually use
+2. **Explicit Dependencies** - Clear which crypto implementations are needed
+3. **Build-time Errors** - Catch missing providers during compilation, not runtime
+4. **Bundle Size** - Reduce bundle size by excluding unused providers
+5. **Environment Flexibility** - Each environment can import only what it needs
+
+### Recommended Import Patterns
+
+**For Web Applications:**
+```typescript
+import '@bananalink-sdk/protocol/crypto/provider/webcrypto';
+import '@bananalink-sdk/protocol/crypto/provider/noble'; // Fallback
+```
+
+**For Node.js Applications:**
+```typescript
+import '@bananalink-sdk/protocol/crypto/provider/node';
+import '@bananalink-sdk/protocol/crypto/provider/noble'; // Fallback
+```
+
+**For React Native Applications:**
+```typescript
+import '@bananalink-sdk/protocol/crypto/provider/quickcrypto';
+import '@bananalink-sdk/protocol/crypto/provider/noble'; // Fallback
+```
+
+**For Universal/Isomorphic Applications:**
+```typescript
+import '@bananalink-sdk/protocol/crypto/provider/noble'; // Works everywhere
+```
+
+### Provider Operations
+
+All providers implement the same `CryptoProvider` interface:
+
+```typescript
+interface CryptoProvider {
+  // Key operations
+  generateKeyPair(): Promise<ProviderKeyPair>;
+  deriveSharedSecret(privateKey: CryptoKeyLike, publicKey: CryptoKeyLike): Promise<ArrayBuffer>;
+
+  // Encryption
+  encrypt(key: CryptoKeyLike, plaintext: Uint8Array, iv: Uint8Array): Promise<ArrayBuffer>;
+  decrypt(key: CryptoKeyLike, ciphertext: Uint8Array, iv: Uint8Array): Promise<ArrayBuffer>;
+
+  // Key management
+  exportPublicKey(key: CryptoKeyLike): Promise<ArrayBuffer>;
+  importPublicKey(keyData: ArrayBuffer): Promise<CryptoKeyLike>;
+  deriveEncryptionKey(sharedSecret: ArrayBuffer, salt: Uint8Array, info: Uint8Array): Promise<CryptoKeyLike>;
+
+  // Utilities
+  randomBytes(length: number): Uint8Array;
+  isAvailable: boolean;
+}
+```
+
+### Advanced Usage
+
+**Check Registered Providers:**
+```typescript
+import { getRegisteredCryptoProviders } from '@bananalink-sdk/protocol/crypto';
+
+const providers = getRegisteredCryptoProviders();
+console.log('Available providers:', providers); // ['noble', 'webcrypto']
+```
+
+**Provider Diagnostics:**
+```typescript
+import { testProvider, diagnoseEnvironment } from '@bananalink-sdk/protocol/crypto';
+
+// Test a specific provider
+const result = await testProvider('noble');
+console.log('Provider test:', result.success ? '✅' : '❌');
+
+// Full environment diagnostics
+const diag = await diagnoseEnvironment();
+console.log(diag.toMarkdown()); // Detailed report
+```
+
+**Compliance Wrapper:**
+```typescript
+import { ComplianceCryptoProvider } from '@bananalink-sdk/protocol/crypto';
+
+const baseProvider = createCryptoProvider('noble');
+const compliantProvider = new ComplianceCryptoProvider(baseProvider, {
+  enabled: true,
+  sessionId: 'my-session',
+  strictMode: true
+});
+```
+
+---
+
+## Design Principles
+
+1. **Type Safety**: All interfaces are strictly typed with comprehensive validation
+2. **Separation of Concerns**: DApp metadata vs session configuration are distinct
+3. **Security First**: Built-in encryption, origin verification, and rate limiting
+4. **Developer Experience**: Clear, documented interfaces with helpful validation errors
+5. **Extensibility**: Modular design allows for future protocol enhancements
+
+For more information, see the [Architecture Documentation](../../ARCHITECTURE.md).