@bananalink-sdk/protocol 1.2.7

package/src/types/index.ts

@@ -0,0 +1,197 @@
+/**
+ * Core types for the BananaLink protocol
+ * Based on ERC-4361 SIWE format with BananaLink extensions
+ */
+
+// Re-export QR Code payload from discovery types
+export type { QRPayload } from './discovery';
+// Re-export provider configuration types
+export type {
+  ProviderType,
+  ProviderConfig,
+  ProviderConfigResponse,
+  UWebSocketConfig,
+  PusherConfig,
+  AblyConfig
+} from './providers';
+
+// Re-export v2.0 wallet message types
+export type {
+  WalletSessionClaim,
+  WalletMessageEnvelope,
+  ClaimSessionPayload,
+  PrefetchMetadataPayload,
+  ConnectionRejectedPayload,
+  AuthenticateConnectionPayload,
+  WalletReconnectPayload,
+  WalletMessagePayload,
+  RejectionData,
+  AuthenticationData,
+  WalletMetadata,
+  WalletHandshakeMessage,
+  ConnectionRejectedMessage,
+  ConnectionAuthenticatedMessage,
+  RelayToDAppMessage,
+  PrefetchMetadataResponse,
+} from './wallet-messages';
+
+// Re-export v2.1+ request lifecycle types
+export type {
+  BaseRequestMetadata,
+  BaseResponseMetadata,
+  BaseRejectionMetadata,
+  RequestRejectionReason,
+  RequestState,
+} from './request-lifecycle';
+
+export {
+  isValidRejectionReason,
+} from './request-lifecycle';
+
+// Re-export v2.1+ signing operation types
+export type {
+  BaseSigningRequest,
+  BaseSigningResponse,
+  SigningRejection,
+} from './signing-operations';
+
+export {
+  isValidSignature,
+  isValidAddress,
+} from './signing-operations';
+
+// Re-export v2.1+ post-authentication operation types
+export type {
+  SignMessageRequest,
+  SignMessageResponse,
+  SignTypedDataRequest,
+  SignTypedDataResponse,
+  EIP712Domain,
+  EIP712TypeDefinition,
+  SignTransactionRequest,
+  SignTransactionResponse,
+  LegacyTransaction,
+  EIP1559Transaction,
+  TransactionRequest,
+  AccessListEntry,
+  SignMessageRequestPayload,
+  SignTypedDataRequestPayload,
+  SignTransactionRequestPayload,
+  RequestFulfilledPayload,
+  RequestRejectedPayload,
+  RequestFulfilledData,
+  RequestRejectedData,
+} from './post-auth-operations';
+
+export {
+  isSignMessageRequest,
+  isSignTypedDataRequest,
+  isSignTransactionRequest,
+  isLegacyTransaction,
+  isEIP1559Transaction,
+  isSignMessageRequestPayload,
+  isSignTypedDataRequestPayload,
+  isSignTransactionRequestPayload,
+  isRequestFulfilledPayload,
+  isRequestRejectedPayload,
+} from './post-auth-operations';
+
+// Re-export wallet message type guards
+export {
+  isClaimSessionPayload,
+  isPrefetchMetadataPayload,
+  isConnectionRejectedPayload,
+  isAuthenticateConnectionPayload,
+  isWalletReconnectPayload,
+  isWalletHandshakeMessage,
+  isConnectionRejectedMessage,
+  isConnectionAuthenticatedMessage,
+} from './wallet-messages';
+
+// Re-export v2.0 client message types
+export type {
+  ClientSessionClaim,
+  ClientMessageEnvelope,
+  ClientReconnectPayload,
+  CloseSessionPayload,
+  ClientMessagePayload,
+} from './client-messages';
+
+// Re-export client message type guards
+export {
+  isClientReconnectPayload,
+  isCloseSessionPayload,
+} from './client-messages';
+
+// Re-export v2.0 relay notification message types
+export type {
+  SessionClosedAck,
+  SessionClosedNotification,
+  ReconnectedMessage,
+  RelayNotificationMessage,
+} from './relay-messages';
+
+// Re-export relay notification message type guards
+export {
+  isSessionClosedAck,
+  isSessionClosedNotification,
+  isReconnectedMessage,
+} from './relay-messages';
+
+// Re-export core types from core.ts (Protocol v2.0 only)
+export type {
+  SIWEFields,
+  DAppMetadata,
+  SessionConfig,
+  SessionOptions,
+  SecurityPolicy,
+  SessionMetadata,
+  CreateSessionRequest,
+  CreateSessionResponse,
+} from './core';
+
+// Re-export discovery and relay types
+export type { RelayMessageType, EncryptedPayload, RelayMessage, DisplayInfo } from './discovery';
+
+// Re-export auth types
+export type { SessionState, SessionInfo, SessionSecurity, OriginProof } from './auth';
+
+// Re-export error types
+export type {
+  BananaLinkErrorCode,
+  WalletRejectionReason,
+  RelayRejectionReason,
+  RejectionReason,
+} from './errors';
+
+// Re-export crypto provider types
+export type {
+  CryptoKeyLike,
+  KeyPairLike,
+  ProviderKeyPair,
+  CryptoProvider,
+  CryptoProviderFactory,
+  CryptoProviderType,
+  PlatformDetectionResult,
+  ProviderDetectionResult,
+} from './crypto-provider';
+
+// Re-export crypto runtime types
+export type {
+  EncryptionAlgorithm,
+  EncryptedMessage,
+  KeyPair,
+  SessionKeys,
+  CryptoConfig,
+  CreatePayloadOptions,
+} from '../crypto/types';
+
+// Re-export crypto payload types (from crypto.ts)
+export type {
+  KeyExchange,
+  Encryption,
+  PublicKeyJWK,
+  CryptoParameters,
+  KeyDerivation,
+  CryptoPayload,
+} from './crypto';

package/src/types/post-auth-operations.ts

@@ -0,0 +1,363 @@
+/**
+ * Post-Authentication Operations Types for BananaLink Protocol v2.0
+ *
+ * This module defines concrete operation types for post-authentication requests:
+ * - Message signing (personal_sign)
+ * - Typed data signing (eth_signTypedData_v4)
+ * - Transaction signing (legacy + EIP-1559)
+ *
+ * All operations follow the request lifecycle defined in request-lifecycle.ts
+ */
+
+import type { EncryptedPayload } from './discovery';
+import type {
+  BaseSigningRequest,
+  BaseSigningResponse,
+  SigningRejection
+} from './signing-operations';
+
+/**
+ * ========================================
+ * MESSAGE SIGNING OPERATIONS
+ * ========================================
+ */
+
+/**
+ * Personal sign request (personal_sign / eth_sign)
+ * Used for signing arbitrary messages
+ *
+ * Security Note: personal_sign is recommended over eth_sign
+ * eth_sign is dangerous and should only be used with explicit user consent
+ */
+export interface SignMessageRequest extends BaseSigningRequest {
+  /**
+   * Message to sign (UTF-8 string or hex-encoded bytes)
+   * Wallet MUST display raw message to user
+   * @example "Sign this message to authenticate"
+   * @example "0x48656c6c6f20576f726c64" (hex-encoded "Hello World")
+   */
+  data: string;
+
+  /**
+   * Signing method
+   * - personal_sign: Prefixes message with "\x19Ethereum Signed Message:\n{length}"
+   * - eth_sign: Direct signing without prefix (DANGEROUS - wallet should warn user)
+   */
+  method: 'personal_sign';
+}
+
+/**
+ * Sign message response
+ */
+export interface SignMessageResponse extends BaseSigningResponse {
+  /** Discriminator for union type matching */
+  requestType: 'sign_message';
+}
+
+/**
+ * ========================================
+ * TYPED DATA SIGNING OPERATIONS (EIP-712)
+ * ========================================
+ */
+
+/**
+ * EIP-712 Domain Separator
+ * Defines the context for typed data signing
+ */
+export interface EIP712Domain {
+  /** Human-readable name of signing domain */
+  name?: string;
+
+  /** Current version of signing domain */
+  version?: string;
+
+  /** Chain ID where signature is valid (EIP-155) */
+  chainId?: number;
+
+  /** Address of contract that will verify signature */
+  verifyingContract?: string;
+
+  /** Salt for domain separation (optional) */
+  salt?: string;
+}
+
+/**
+ * EIP-712 Type Definition
+ * Defines structure of a custom type
+ */
+export interface EIP712TypeDefinition {
+  name: string;
+  type: string;
+}
+
+/**
+ * Typed data sign request (EIP-712)
+ * Used for structured data signing (permits, orders, etc.)
+ */
+export interface SignTypedDataRequest extends BaseSigningRequest {
+  /**
+   * EIP-712 typed data object
+   * Wallet MUST validate structure and display human-readable form
+   */
+  data: {
+    /** Domain separator for signature context */
+    domain: EIP712Domain;
+
+    /** Type definitions (excluding EIP712Domain) */
+    types: Record<string, EIP712TypeDefinition[]>;
+
+    /** Primary type name (must be defined in types) */
+    primaryType: string;
+
+    /** Message data matching primaryType structure */
+    message: Record<string, unknown>;
+  };
+
+  /**
+   * Signing method version
+   * Only v4 supported (v1-v3 deprecated)
+   */
+  method: 'eth_signTypedData_v4';
+}
+
+/**
+ * Sign typed data response
+ */
+export interface SignTypedDataResponse extends BaseSigningResponse {
+  /** Discriminator for union type matching */
+  requestType: 'sign_typed_data';
+}
+
+/**
+ * ========================================
+ * TRANSACTION SIGNING OPERATIONS
+ * ========================================
+ */
+
+/**
+ * Transaction access list entry (EIP-2930)
+ * Specifies accounts and storage slots accessed by transaction
+ */
+export interface AccessListEntry {
+  /** Account address */
+  address: string;
+
+  /** Storage keys accessed in this account */
+  storageKeys: string[];
+}
+
+/**
+ * Legacy transaction (pre-EIP-1559)
+ * Uses fixed gas price model
+ */
+export interface LegacyTransaction {
+  /** Transaction type discriminator */
+  type: 'legacy';
+
+  /** Recipient address (0x-prefixed, 42 chars) */
+  to: string;
+
+  /** Value in wei (hex-encoded, 0x-prefixed) */
+  value: string;
+
+  /** Transaction data (hex-encoded, 0x-prefixed, optional) */
+  data?: string;
+
+  /** Transaction nonce (hex-encoded, 0x-prefixed) */
+  nonce: string;
+
+  /** Gas limit (hex-encoded, 0x-prefixed) */
+  gasLimit: string;
+
+  /** Gas price in wei (hex-encoded, 0x-prefixed) */
+  gasPrice: string;
+
+  /** Chain ID (EIP-155) */
+  chainId: number;
+}
+
+/**
+ * EIP-1559 transaction
+ * Uses base fee + priority fee model
+ */
+export interface EIP1559Transaction {
+  /** Transaction type discriminator */
+  type: 'eip1559';
+
+  /** Recipient address */
+  to: string;
+
+  /** Value in wei (hex-encoded) */
+  value: string;
+
+  /** Transaction data (hex-encoded, optional) */
+  data?: string;
+
+  /** Transaction nonce (hex-encoded) */
+  nonce: string;
+
+  /** Gas limit (hex-encoded) */
+  gasLimit: string;
+
+  /** Max priority fee per gas in wei (hex-encoded) */
+  maxPriorityFeePerGas: string;
+
+  /** Max fee per gas in wei (hex-encoded) */
+  maxFeePerGas: string;
+
+  /** Chain ID (EIP-155) */
+  chainId: number;
+
+  /** Access list (EIP-2930, optional) */
+  accessList?: AccessListEntry[];
+}
+
+/**
+ * Transaction request union type
+ */
+export type TransactionRequest = LegacyTransaction | EIP1559Transaction;
+
+/**
+ * Sign transaction request
+ * Used for signing transactions (NOT broadcasting)
+ */
+export interface SignTransactionRequest extends Omit<BaseSigningRequest, 'data'> {
+  /**
+   * Transaction parameters
+   * Wallet MUST validate all fields before signing
+   */
+  data: TransactionRequest;
+
+  /**
+   * Signing method (always eth_signTransaction)
+   */
+  method: 'eth_signTransaction';
+}
+
+/**
+ * Sign transaction response
+ */
+export interface SignTransactionResponse extends BaseSigningResponse {
+  /** Discriminator for union type matching */
+  requestType: 'sign_transaction';
+
+  /**
+   * RLP-encoded signed transaction
+   * Format: 0x-prefixed hex string
+   * Can be broadcast to network via eth_sendRawTransaction
+   */
+  signedTransaction: string;
+}
+
+/**
+ * ========================================
+ * PAYLOAD TYPES (ENCRYPTED WRAPPERS)
+ * ========================================
+ */
+
+/**
+ * Sign message request payload (dApp → Wallet)
+ */
+export interface SignMessageRequestPayload {
+  type: 'sign_message_request';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Sign typed data request payload (dApp → Wallet)
+ */
+export interface SignTypedDataRequestPayload {
+  type: 'sign_typed_data_request';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Sign transaction request payload (dApp → Wallet)
+ */
+export interface SignTransactionRequestPayload {
+  type: 'sign_transaction_request';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Request fulfilled response payload (Wallet → dApp)
+ * Used for all successful request completions
+ */
+export interface RequestFulfilledPayload {
+  type: 'request_fulfilled';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Request rejected response payload (Wallet → dApp)
+ * Used when wallet rejects a request
+ */
+export interface RequestRejectedPayload {
+  type: 'request_rejected';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Union type for request fulfilled data (decrypted)
+ */
+export type RequestFulfilledData =
+  | SignMessageResponse
+  | SignTypedDataResponse
+  | SignTransactionResponse;
+
+/**
+ * Request rejected data (decrypted)
+ */
+export interface RequestRejectedData extends SigningRejection {
+  /** Original request type being rejected */
+  requestType: 'sign_message' | 'sign_typed_data' | 'sign_transaction';
+}
+
+/**
+ * ========================================
+ * TYPE GUARDS
+ * ========================================
+ */
+
+export function isSignMessageRequest(req: unknown): req is SignMessageRequest {
+  const r = req as SignMessageRequest;
+  return r?.method === 'personal_sign' && typeof r?.data === 'string';
+}
+
+export function isSignTypedDataRequest(req: unknown): req is SignTypedDataRequest {
+  const r = req as SignTypedDataRequest;
+  return r?.method === 'eth_signTypedData_v4' && typeof r?.data === 'object';
+}
+
+export function isSignTransactionRequest(req: unknown): req is SignTransactionRequest {
+  const r = req as SignTransactionRequest;
+  return r?.method === 'eth_signTransaction' && typeof r?.data === 'object';
+}
+
+export function isLegacyTransaction(tx: TransactionRequest): tx is LegacyTransaction {
+  return tx.type === 'legacy';
+}
+
+export function isEIP1559Transaction(tx: TransactionRequest): tx is EIP1559Transaction {
+  return tx.type === 'eip1559';
+}
+
+export function isSignMessageRequestPayload(payload: unknown): payload is SignMessageRequestPayload {
+  return (payload as SignMessageRequestPayload)?.type === 'sign_message_request';
+}
+
+export function isSignTypedDataRequestPayload(payload: unknown): payload is SignTypedDataRequestPayload {
+  return (payload as SignTypedDataRequestPayload)?.type === 'sign_typed_data_request';
+}
+
+export function isSignTransactionRequestPayload(payload: unknown): payload is SignTransactionRequestPayload {
+  return (payload as SignTransactionRequestPayload)?.type === 'sign_transaction_request';
+}
+
+export function isRequestFulfilledPayload(payload: unknown): payload is RequestFulfilledPayload {
+  return (payload as RequestFulfilledPayload)?.type === 'request_fulfilled';
+}
+
+export function isRequestRejectedPayload(payload: unknown): payload is RequestRejectedPayload {
+  return (payload as RequestRejectedPayload)?.type === 'request_rejected';
+}

package/src/types/providers.ts

@@ -0,0 +1,72 @@
+/**
+ * Provider Configuration Types
+ * Types for transport provider configuration and management
+ */
+
+/**
+ * Supported transport provider types (API response format)
+ * Note: 'uwebsockets' is maintained for API compatibility but SDKs normalize to 'websocket'
+ */
+export type ProviderType = 'uwebsockets' | 'websocket' | 'pusher' | 'ably';
+
+/**
+ * Base provider configuration
+ */
+export interface ProviderConfig {
+  providerId: string;
+  type: ProviderType;
+  enabled: boolean;
+  priority: number;
+  config: UWebSocketConfig | PusherConfig | AblyConfig;
+  features?: string[];
+}
+
+/**
+ * Provider configuration response from API Gateway
+ */
+export interface ProviderConfigResponse {
+  providers: ProviderConfig[];
+  ttl: number;
+  lastUpdated: string;
+}
+
+/**
+ * UWebSocket provider configuration
+ */
+export interface UWebSocketConfig {
+  relayUrl: string;
+  maxConnections?: number;
+  reconnectInterval?: number;
+  heartbeatInterval?: number;
+  maxPayloadLength?: number;
+  idleTimeout?: number;
+  fallbackUrl?: string;
+}
+
+/**
+ * Pusher provider configuration
+ */
+export interface PusherConfig {
+  appKey: string;
+  key?: string;
+  cluster: string;
+  encrypted?: boolean;
+  authEndpoint?: string;
+  useTLS?: boolean;
+  host?: string;
+  timeout?: number;
+}
+
+/**
+ * Ably provider configuration
+ */
+export interface AblyConfig {
+  apiKey: string;
+  key?: string;
+  clientId?: string;
+  authUrl?: string;
+  environment?: string;
+  tls?: boolean;
+  timeout?: number;
+  clientOptions?: Record<string, unknown>;
+}

package/src/types/relay-messages.ts

@@ -0,0 +1,60 @@
+/**
+ * Relay notification message types for BananaLink protocol v2.0
+ * These are messages sent from relay server to clients/wallets
+ */
+
+/**
+ * Session closed acknowledgment
+ * Sent to acknowledge a close_session request
+ */
+export interface SessionClosedAck {
+  type: 'session_closed_ack';
+  timestamp: number;
+}
+
+/**
+ * Session closed notification
+ * Sent to notify the other party that peer closed the session
+ */
+export interface SessionClosedNotification {
+  type: 'session_closed_notification';
+  /** Which party closed the session */
+  closedBy: 'client' | 'wallet';
+  /** Optional reason for closure */
+  reason?: string;
+  timestamp: number;
+}
+
+/**
+ * Reconnected confirmation message
+ * Sent after successful reconnection
+ */
+export interface ReconnectedMessage {
+  type: 'reconnected';
+  /** Number of messages that were queued during disconnection */
+  queuedMessages: number;
+  timestamp: number;
+}
+
+/**
+ * Union type for relay notification messages
+ */
+export type RelayNotificationMessage =
+  | SessionClosedAck
+  | SessionClosedNotification
+  | ReconnectedMessage;
+
+/**
+ * Type guards for relay notification messages
+ */
+export function isSessionClosedAck(message: RelayNotificationMessage): message is SessionClosedAck {
+  return message?.type === 'session_closed_ack';
+}
+
+export function isSessionClosedNotification(message: RelayNotificationMessage): message is SessionClosedNotification {
+  return message?.type === 'session_closed_notification';
+}
+
+export function isReconnectedMessage(message: RelayNotificationMessage): message is ReconnectedMessage {
+  return message?.type === 'reconnected';
+}