@bananalink-sdk/protocol 1.2.7

package/src/types/client-messages.ts

@@ -0,0 +1,84 @@
+/**
+ * Client message types for BananaLink protocol v2.0
+ * These types define the communication between dApp clients and the relay server
+ */
+
+import type {
+  SignMessageRequestPayload,
+  SignTypedDataRequestPayload,
+  SignTransactionRequestPayload,
+} from './post-auth-operations';
+
+/**
+ * Client session claim credential for authentication and reconnection
+ * Stored by client, validated by relay server
+ */
+export interface ClientSessionClaim {
+  /**
+   * Unique nonce for this client session
+   * - Generated once by client during session creation
+   * - Stored locally by client for reconnection
+   * - Used by relay to validate client ownership
+   * - Different for each session
+   */
+  claimNonce: string;
+
+  /** Claim generation timestamp */
+  timestamp: number;
+}
+
+/**
+ * Client reconnect payload
+ * Used to reconnect after network interruption
+ */
+export interface ClientReconnectPayload {
+  type: 'client_reconnect';
+}
+
+/**
+ * Close session payload
+ * Used to gracefully close a session (bidirectional)
+ */
+export interface CloseSessionPayload {
+  type: 'close_session';
+  /** Optional reason for closing the session */
+  reason?: string;
+}
+
+/**
+ * Union type for all client message payloads
+ */
+export type ClientMessagePayload =
+  // Session management payloads
+  | ClientReconnectPayload
+  | CloseSessionPayload
+  // Post-authentication operation request payloads (v2.1+)
+  | SignMessageRequestPayload
+  | SignTypedDataRequestPayload
+  | SignTransactionRequestPayload;
+
+/**
+ * Client message envelope structure
+ * All client-to-relay messages use this envelope
+ */
+export interface ClientMessageEnvelope {
+  /** Session identifier */
+  sessionId: string;
+
+  /** Client session claim - validated by relay server */
+  clientSessionClaim: ClientSessionClaim;
+
+  /** Actual message payload */
+  payload: ClientMessagePayload;
+}
+
+/**
+ * Type guards for client messages
+ */
+export function isClientReconnectPayload(payload: ClientMessagePayload): payload is ClientReconnectPayload {
+  return payload?.type === 'client_reconnect';
+}
+
+export function isCloseSessionPayload(payload: ClientMessagePayload): payload is CloseSessionPayload {
+  return payload?.type === 'close_session';
+}

package/src/types/core.ts

@@ -0,0 +1,131 @@
+/**
+ * Core types for the BananaLink protocol
+ * Based on ERC-4361 SIWE format with BananaLink extensions
+ */
+
+// Base SIWE types from ERC-4361
+export interface SIWEFields {
+  /** The URI scheme of the origin of the request */
+  scheme?: string;
+  /** The domain that is requesting the signing */
+  domain: string;
+  /** The Ethereum address performing the signing */
+  address: string;
+  /** A human-readable ASCII assertion that the user will sign */
+  statement?: string;
+  /** An RFC 3986 URI referring to the resource that is the subject of the signing */
+  uri: string;
+  /** The current version of the SIWE Message, which MUST be 1 */
+  version: string;
+  /** The EIP-155 Chain ID to which the session is bound */
+  chainId: number;
+  /** A random string used to prevent replay attacks, at least 8 alphanumeric characters */
+  nonce: string;
+  /** The time when the message was generated, ISO 8601 datetime string */
+  issuedAt: string;
+  /** The time when the signed authentication message is no longer valid */
+  expirationTime?: string;
+  /** The time when the signed authentication message will become valid */
+  notBefore?: string;
+  /** A system-specific identifier that MAY be used to uniquely refer to the sign-in request */
+  requestId?: string;
+  /** A list of information or references to information the user wishes to have resolved */
+  resources?: string[];
+}
+
+// DApp metadata for registration and discovery
+export interface DAppMetadata {
+  /** DApp unique identifier */
+  dappId?: string;
+  /** Name of the dApp */
+  name: string;
+  /** Description of the dApp */
+  description?: string;
+  /** URL of the dApp */
+  url: string;
+  /** Array of icon URLs */
+  icons?: string[];
+}
+
+// Session-specific configuration
+export interface SessionConfig {
+  /** URL to redirect to after session completion */
+  returnUrl?: string;
+  /** Human-readable session identifier */
+  sessionName?: string;
+  /** Session-specific expiration override */
+  expiresAt?: string;
+  /** Custom session data */
+  customData?: Record<string, unknown>;
+}
+
+// Session creation options
+export interface SessionOptions {
+  /** Session-specific configuration */
+  config?: SessionConfig;
+  /** Security policy overrides */
+  securityPolicy?: Partial<SecurityPolicy>;
+  /** Relay server URL override */
+  relayUrl?: string;
+}
+
+// Security policy configuration
+export interface SecurityPolicy {
+  /** Session timeout in milliseconds */
+  sessionTimeout: number;
+  /** Request timeout in milliseconds */
+  requestTimeout: number;
+  /** Maximum concurrent sessions */
+  maxConcurrentSessions: number;
+  /** Require origin proof */
+  requireOriginProof: boolean;
+  /** Allowed domains whitelist */
+  allowedDomains?: string[];
+  /** Blocked domains blacklist */
+  blockedDomains?: string[];
+}
+
+// Session creation API types (HTTP Request/Response)
+/**
+ * Session metadata for session creation
+ * Simplified cryptographic metadata
+ */
+export interface SessionMetadata {
+  /** Encryption algorithm */
+  encryptionAlgorithm: 'AES-GCM' | 'plaintext';
+  /** Session identifier (exchange session ID) */
+  sessionId: string;
+  /** Base64-encoded public key (required for AES-GCM) */
+  publicKey?: string;
+  /** Timestamp when metadata was created */
+  timestamp: string;
+}
+
+/**
+ * Session creation request (Client → API Gateway)
+ */
+export interface CreateSessionRequest {
+  /** DApp unique identifier */
+  dappId: string;
+  /** Session cryptographic metadata */
+  metadata: SessionMetadata;
+  /** Optional session configuration */
+  sessionConfig?: SessionConfig;
+}
+
+/**
+ * Session creation response (API Gateway → Client)
+ */
+export interface CreateSessionResponse {
+  /** Generated session identifier */
+  sessionId: string;
+  /** Client session claim for reconnection */
+  clientSessionClaim: {
+    /** Unique claim nonce */
+    claimNonce: string;
+    /** Claim timestamp */
+    timestamp: number;
+  };
+  /** Session time-to-live in seconds */
+  ttl: number;
+}

package/src/types/crypto-provider.ts

@@ -0,0 +1,264 @@
+/**
+ * Crypto Provider Interface Types
+ *
+ * Pure TypeScript type definitions for environment-agnostic cryptographic operations.
+ * These types define the contract that crypto providers must implement.
+ *
+ * IMPORTANT: This file contains ONLY type definitions with zero runtime code.
+ * Actual implementations will be in the crypto/ directory.
+ */
+
+/**
+ * Generic crypto key interface compatible across different crypto providers
+ * Provides a minimal contract that works with Web Crypto API, Node.js crypto, and pure JS implementations
+ */
+export interface CryptoKeyLike {
+  readonly type: 'public' | 'private' | 'secret';
+  readonly algorithm: string;
+  readonly extractable: boolean;
+  readonly usages: readonly string[];
+}
+
+/**
+ * Key pair structure for asymmetric cryptography
+ */
+export interface KeyPairLike {
+  publicKey: CryptoKeyLike;
+  privateKey: CryptoKeyLike;
+}
+
+/**
+ * Provider-specific key pair (alias for compatibility)
+ */
+export interface ProviderKeyPair {
+  publicKey: CryptoKeyLike;
+  privateKey: CryptoKeyLike;
+}
+
+/**
+ * Environment-agnostic crypto provider interface
+ *
+ * This interface abstracts cryptographic operations to work across different environments:
+ * - Browser (Web Crypto API)
+ * - Node.js (crypto module / QuickCrypto)
+ * - React Native (@noble/curves fallback)
+ *
+ * All implementations must support:
+ * - ECDH P-256 for key exchange
+ * - AES-256-GCM for encryption
+ * - HKDF-SHA256 for key derivation
+ * - HMAC-SHA256 for authentication
+ */
+export interface CryptoProvider {
+  /** Provider name for identification and debugging */
+  readonly name: string;
+
+  /** Whether this provider is available in the current environment */
+  readonly isAvailable: boolean;
+
+  /**
+   * Generate ECDH P-256 key pair for key exchange
+   * @returns Promise resolving to public/private key pair
+   */
+  generateKeyPair(): Promise<ProviderKeyPair>;
+
+  /**
+   * Export public key to raw ArrayBuffer format (65 bytes uncompressed)
+   * @param publicKey - Public key to export
+   * @returns Promise resolving to raw key bytes
+   */
+  exportPublicKey(publicKey: CryptoKeyLike): Promise<ArrayBuffer>;
+
+  /**
+   * Export private key to raw ArrayBuffer format (32 bytes)
+   * @param privateKey - Private key to export
+   * @returns Promise resolving to raw key bytes
+   */
+  exportPrivateKey(privateKey: CryptoKeyLike): Promise<ArrayBuffer>;
+
+  /**
+   * Import public key from raw ArrayBuffer format
+   * @param keyData - Raw key bytes (65 bytes uncompressed)
+   * @returns Promise resolving to imported public key
+   */
+  importPublicKey(keyData: ArrayBuffer): Promise<CryptoKeyLike>;
+
+  /**
+   * Import private key from raw ArrayBuffer format
+   * @param keyData - Raw key bytes (32 bytes)
+   * @returns Promise resolving to imported private key
+   */
+  importPrivateKey(keyData: ArrayBuffer): Promise<CryptoKeyLike>;
+
+  /**
+   * Derive shared secret from ECDH key agreement
+   * @param privateKey - Local private key
+   * @param publicKey - Remote public key
+   * @returns Promise resolving to shared secret (raw key material)
+   */
+  deriveSharedSecret(
+    privateKey: CryptoKeyLike,
+    publicKey: CryptoKeyLike,
+  ): Promise<CryptoKeyLike>;
+
+  /**
+   * Derive AES-GCM encryption key from shared secret using HKDF
+   * @param sharedSecret - The shared secret from ECDH
+   * @param salt - Random salt for HKDF (recommended: 32 bytes)
+   * @param info - Context-specific info string for HKDF
+   * @returns Promise resolving to AES-256-GCM key
+   */
+  deriveEncryptionKey(
+    sharedSecret: CryptoKeyLike,
+    salt: ArrayBuffer,
+    info: ArrayBuffer,
+  ): Promise<CryptoKeyLike>;
+
+  /**
+   * Generate cryptographically secure random bytes
+   * @param length - Number of bytes to generate
+   * @returns ArrayBuffer containing random bytes
+   */
+  randomBytes(length: number): ArrayBuffer;
+
+  /**
+   * Encrypt data using AES-256-GCM
+   * @param key - AES-GCM encryption key
+   * @param data - Plaintext data to encrypt
+   * @param iv - Initialization vector (12 bytes for GCM)
+   * @returns Promise resolving to ciphertext with authentication tag
+   */
+  encrypt(
+    key: CryptoKeyLike,
+    data: ArrayBuffer,
+    iv: ArrayBuffer,
+  ): Promise<ArrayBuffer>;
+
+  /**
+   * Decrypt data using AES-256-GCM
+   * @param key - AES-GCM decryption key
+   * @param data - Ciphertext with authentication tag
+   * @param iv - Initialization vector (12 bytes for GCM)
+   * @returns Promise resolving to decrypted plaintext
+   * @throws Error if authentication tag verification fails
+   */
+  decrypt(
+    key: CryptoKeyLike,
+    data: ArrayBuffer,
+    iv: ArrayBuffer,
+  ): Promise<ArrayBuffer>;
+
+  /**
+   * Generate HMAC-SHA256 authentication code
+   * @param key - HMAC key (derived from AES key)
+   * @param data - Data to authenticate
+   * @returns Promise resolving to HMAC (32 bytes)
+   */
+  generateHMAC(key: CryptoKeyLike, data: ArrayBuffer): Promise<ArrayBuffer>;
+
+  /**
+   * Verify HMAC-SHA256 authentication code
+   * @param key - HMAC key (derived from AES key)
+   * @param data - Data to verify
+   * @param mac - Expected HMAC value
+   * @returns Promise resolving to true if MAC is valid, false otherwise
+   */
+  verifyHMAC(
+    key: CryptoKeyLike,
+    data: ArrayBuffer,
+    mac: ArrayBuffer,
+  ): Promise<boolean>;
+}
+
+/**
+ * Factory function type for creating crypto provider instances
+ */
+export type CryptoProviderFactory = () => CryptoProvider;
+
+/**
+ * Supported crypto provider types
+ * - webcrypto: Web Crypto API (browsers, modern Node.js)
+ * - node: Node.js native crypto (backend services, highest performance)
+ * - noble: @noble/curves (pure JavaScript, universal fallback)
+ * - quickcrypto: Node.js native crypto or QuickCrypto (performance optimized)
+ */
+export type CryptoProviderType = 'webcrypto' | 'node' | 'noble' | 'quickcrypto';
+
+/**
+ * Platform detection result
+ * Used to determine the best crypto provider for the current environment
+ */
+export interface PlatformDetectionResult {
+  /** Running in Node.js */
+  isNode: boolean;
+  /** Running in browser */
+  isBrowser: boolean;
+  /** Running in React Native */
+  isReactNative: boolean;
+  /** Platform identifier (e.g., 'darwin', 'linux', 'win32') */
+  platform?: string;
+  /** Browser user agent string */
+  userAgent?: string;
+}
+
+/**
+ * Granular capability information for a specific cryptographic operation
+ */
+export interface OperationCapability {
+  /** Whether this operation is available */
+  available: boolean;
+  /** Reason for unavailability (if available=false) */
+  reason?: string;
+}
+
+/**
+ * Detailed provider capabilities by operation type
+ * Used for granular detection and diagnostic reporting
+ */
+export interface CryptoCapabilities {
+  /** ECDH P-256 key exchange operations */
+  ecdh: OperationCapability;
+  /** AES-256-GCM encryption/decryption */
+  aesGcm: OperationCapability;
+  /** HMAC-SHA256 operations */
+  hmac: OperationCapability;
+  /** Random byte generation */
+  randomBytes: OperationCapability;
+  /** Overall provider availability */
+  overall: OperationCapability;
+}
+
+/**
+ * Provider availability detection result
+ * Reports which crypto providers are available in the current environment
+ */
+export interface ProviderDetectionResult {
+  /** Web Crypto API available */
+  webCrypto: boolean;
+  /** Node.js native crypto available */
+  node: boolean;
+  /** @noble/curves available */
+  noble: boolean;
+  /** QuickCrypto/Node crypto available */
+  quickCrypto: boolean;
+  /** Recommended provider for this environment */
+  recommended: CryptoProviderType;
+  /** Detected platform information */
+  platform: PlatformDetectionResult;
+}
+
+/**
+ * Enhanced provider detection with detailed capabilities
+ * Extends base detection with per-operation capability reporting
+ */
+export interface EnhancedProviderDetectionResult extends ProviderDetectionResult {
+  /** Detailed capability breakdown per provider */
+  capabilities: {
+    webcrypto?: CryptoCapabilities;
+    node?: CryptoCapabilities;
+    noble: CryptoCapabilities;
+    quickcrypto?: CryptoCapabilities;
+  };
+  /** Human-readable recommendations for developers */
+  recommendations: string[];
+}

package/src/types/crypto.ts

@@ -0,0 +1,90 @@
+/**
+ * Crypto payload types for BananaLink message encryption/decryption
+ * Based on crypto_payload_spec.md
+ */
+
+/**
+ * Key exchange algorithm specification
+ */
+export interface KeyExchange {
+  /** Elliptic Curve Diffie-Hellman */
+  algorithm: 'ECDH';
+  /** NIST P-256 curve (secp256r1) */
+  namedCurve: 'P-256';
+}
+
+/**
+ * Encryption algorithm specification
+ */
+export interface Encryption {
+  /** Encryption algorithm */
+  algorithm: 'AES-GCM' | 'plaintext';
+  /** AES key length in bits (production only) */
+  keyLength?: 256;
+  /** GCM authentication tag length (production only) */
+  tagLength?: 128;
+}
+
+/**
+ * Public key in JWK format for ECDH
+ */
+export interface PublicKeyJWK {
+  /** Key type: Elliptic Curve */
+  kty: 'EC';
+  /** Curve name */
+  crv: 'P-256';
+  /** X coordinate of public key (base64url) */
+  x: string;
+  /** Y coordinate of public key (base64url) */
+  y: string;
+  /** Intended use: encryption */
+  use: 'enc';
+  /** Permitted key operations */
+  key_ops: ['deriveKey'];
+}
+
+/**
+ * Algorithm parameters and metadata
+ */
+export interface CryptoParameters {
+  /** Base64-encoded initialization vector (12 bytes for GCM) */
+  iv?: string;
+  /** ISO 8601 timestamp for replay protection */
+  timestamp: string;
+  /** Unique session identifier for message correlation */
+  sessionId: string;
+}
+
+/**
+ * Key derivation specification
+ */
+export interface KeyDerivation {
+  /** HMAC-based Key Derivation Function */
+  algorithm: 'HKDF';
+  /** Hash function for HKDF */
+  hash: 'SHA-256';
+  /** Application-specific context info */
+  info: 'message-exchange-v1';
+  /** Random salt for key derivation (base64) */
+  salt: string;
+}
+
+/**
+ * Union type for crypto payload
+ */
+export interface CryptoPayload {
+  /** Schema version */
+  version: '1.0';
+  /** Key exchange algorithm specification */
+  keyExchange?: KeyExchange;
+  /** Encryption algorithm specification */
+  encryption: Encryption & { algorithm: 'AES-GCM' | 'plaintext' };
+  /** Public key in JWK format */
+  publicKey?: PublicKeyJWK;
+  /** Algorithm parameters and metadata */
+  parameters: CryptoParameters;
+  /** Key derivation specification */
+  derivation?: KeyDerivation;
+}
+
+

package/src/types/discovery.ts

@@ -0,0 +1,50 @@
+/**
+ * Discovery types for the BananaLink protocol
+ */
+
+// QR Code payload for discovery
+export interface QRPayload {
+  /** Session identifier */
+  sessionId: string;
+  /** Public key with encryption algorithm (format: "enc_algo:public_key_base64") */
+  publicKey: string;
+  /** Optional relay URL for direct connection (overrides provider selection) */
+  relayUrl?: string;
+  /** Optional provider hint for transport selection */
+  providerId?: string;
+}
+
+// Display information for QR/FrutiLink
+export interface DisplayInfo {
+  /** QR code data URL */
+  qrCode: string;
+  /** FrutiLink emoji sequence */
+  frutiLink: string;
+  /** Deep link URL */
+  deepLink: string;
+}
+
+// Relay server message types
+export type RelayMessageType = 'pub' | 'sub' | 'ack' | 'error';
+
+// Encrypted payload for secure communication
+export interface EncryptedPayload {
+  /** Base64 encoded initialization vector */
+  iv: string;
+  /** Base64 encoded ciphertext */
+  ciphertext: string;
+  /** Base64 encoded HMAC for integrity */
+  mac: string;
+}
+
+// Relay server message
+export interface RelayMessage {
+  /** Session ID used as topic */
+  topic: string;
+  /** Message type */
+  type: RelayMessageType;
+  /** Encrypted payload (optional for control messages) */
+  payload?: EncryptedPayload;
+  /** Message ID for acknowledgment */
+  id: string;
+}

package/src/types/errors.ts

@@ -0,0 +1,87 @@
+/**
+ * Error types for the BananaLink protocol v2.0
+ */
+
+// Error codes for BananaLink protocol
+// Organized hierarchically for better maintainability
+export type BananaLinkErrorCode =
+  // ===== SESSION ERRORS =====
+  | 'SESSION_EXPIRED'
+  | 'SESSION_NOT_FOUND'
+  | 'SESSION_ALREADY_CLAIMED'
+  | 'INVALID_SESSION_CLAIM'
+  | 'INVALID_CLIENT_CLAIM'
+  | 'SESSION_TOKEN_EXPIRED'
+  | 'SESSION_CLOSED'
+
+  // ===== ENCRYPTION ERRORS =====
+  | 'ENCRYPTION_FAILED'
+  | 'DECRYPTION_FAILED'
+  | 'INVALID_SIGNATURE'
+
+  // ===== NETWORK ERRORS =====
+  | 'NETWORK_ERROR'
+  | 'RELAY_ERROR'
+  | 'MESSAGE_QUEUE_FULL'
+  | 'RATE_LIMIT_EXCEEDED'
+  | 'ORIGIN_MISMATCH'
+
+  // ===== REQUEST LIFECYCLE ERRORS (v2.1+) =====
+  | 'REQUEST_PENDING'           // Another request already pending
+  | 'REQUEST_NOT_FOUND'         // Request ID not found
+  | 'REQUEST_EXPIRED'           // Request TTL exceeded
+  | 'REQUEST_INVALID'           // Malformed request
+  | 'REQUEST_TIMEOUT'           // Wallet didn't respond in time
+
+  // ===== OPERATION-SPECIFIC ERRORS (v2.1+) =====
+  | 'SIGNING_FAILED'            // Generic signing error
+  | 'SIGNING_REJECTED'          // User rejected signing
+  | 'TRANSACTION_INVALID'       // Transaction validation failed
+  | 'CHAIN_MISMATCH';           // Chain ID doesn't match wallet
+
+/**
+ * Error response format for protocol v2.0
+ * Used for standardized error responses in the BananaLink protocol
+ */
+export interface ProtocolErrorResponse {
+  /** Error type discriminator */
+  type: 'error';
+  /** Error code from BananaLinkErrorCode */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Wallet-initiated rejection reasons
+ * Used in connection_rejected messages
+ */
+export type WalletRejectionReason =
+  | 'user_declined'           // User explicitly rejected connection
+  | 'untrusted_dapp'          // dApp not in user's trusted list
+  | 'unsupported_chain'       // Requested chain not supported by wallet
+  | 'insufficient_balance'    // Wallet has insufficient gas
+  | 'wallet_locked'           // Wallet is locked/requires authentication
+  | 'timeout'                 // User didn't respond within timeout
+  | 'security_warning'        // Security scan flagged dApp
+  | 'rate_limited';           // Too many connection requests
+
+/**
+ * Relay-initiated rejection reasons
+ * Used when relay server rejects a connection
+ */
+export type RelayRejectionReason =
+  | 'session_already_claimed' // Session claimed by another wallet
+  | 'invalid_credentials'     // Session token/claim invalid
+  | 'session_expired'         // Session TTL exceeded before claim
+  | 'session_closed'          // Session explicitly closed
+  | 'dapp_metadata_missing'   // Cannot fetch dApp metadata
+  | 'encryption_mismatch'     // Incompatible encryption algorithms
+  | 'relay_overloaded';       // Relay at capacity
+
+/**
+ * All possible rejection reasons
+ */
+export type RejectionReason = WalletRejectionReason | RelayRejectionReason;