@bananalink-sdk/protocol 1.2.7

package/src/types/request-lifecycle.ts

@@ -0,0 +1,161 @@
+/**
+ * Request Lifecycle Types for BananaLink Protocol v2.0
+ *
+ * This module defines the foundational types for the post-authentication request lifecycle.
+ * All post-authentication operations (signing, transactions, etc.) inherit from these base types.
+ *
+ * Design Principles:
+ * - Base types are operation-agnostic (work for any post-auth operation)
+ * - Request/response correlation via requestId
+ * - Extensible metadata fields for future enhancements
+ * - Clear separation: lifecycle management vs operation-specific logic
+ */
+
+/**
+ * Base request metadata shared by all post-authentication operations
+ * Provides extensibility for future request types
+ */
+export interface BaseRequestMetadata {
+  /**
+   * Unique request identifier (UUID v4)
+   * Generated by dApp, used to match request with response
+   * MUST be unique within session scope
+   */
+  requestId: string;
+
+  /**
+   * Human-readable description of the request
+   * Displayed to user in wallet UI
+   * @example "Sign transaction to mint NFT"
+   * @example "Authenticate with dApp"
+   */
+  description?: string;
+
+  /**
+   * Request creation timestamp (Unix milliseconds)
+   * Used for request expiration and audit logging
+   */
+  timestamp: number;
+
+  /**
+   * Optional metadata for dApp-specific context
+   * Not interpreted by protocol, passed through to wallet
+   * Useful for analytics, debugging, and custom wallet UIs
+   * @example { "transactionType": "nft_mint", "collection": "0x..." }
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Base response metadata for all fulfilled requests
+ */
+export interface BaseResponseMetadata {
+  /**
+   * Request ID this response corresponds to
+   * MUST match the original request's requestId
+   * Used by dApp SDK to correlate request → response
+   */
+  requestId: string;
+
+  /**
+   * Response timestamp (Unix milliseconds)
+   */
+  timestamp: number;
+
+  /**
+   * Optional metadata from wallet
+   * Can include wallet-specific information
+   * @example { "signingMethod": "hardware_wallet", "device": "Ledger Nano S" }
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Base rejection metadata for all rejected requests
+ */
+export interface BaseRejectionMetadata {
+  /**
+   * Request ID being rejected
+   */
+  requestId: string;
+
+  /**
+   * Rejection reason code
+   * See RequestRejectionReason for standard codes
+   */
+  reason: RequestRejectionReason;
+
+  /**
+   * Human-readable rejection message
+   * Optional, for debugging/logging
+   * Should NOT be displayed to end users (use reason code for i18n)
+   */
+  message?: string;
+
+  /**
+   * Rejection timestamp (Unix milliseconds)
+   */
+  timestamp: number;
+
+  /**
+   * Optional rejection context
+   * Can include additional details about the rejection
+   * @example { "validationErrors": ["insufficient_balance"], "required": "0.1 ETH" }
+   */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Request rejection reasons (wallet-initiated)
+ *
+ * These are user-facing or validation-driven rejections from the wallet.
+ * Protocol-level errors (e.g., PENDING_REQUEST_EXISTS) use the error code system instead.
+ */
+export type RequestRejectionReason =
+  | 'user_rejected'           // User explicitly rejected in wallet UI
+  | 'request_expired'         // Request expired before user action
+  | 'invalid_parameters'      // Request parameters validation failed
+  | 'unsupported_operation'   // Wallet doesn't support this operation
+  | 'insufficient_balance'    // Insufficient funds for transaction
+  | 'security_warning'        // Security scan flagged request
+  | 'wallet_locked'           // Wallet locked during request
+  | 'network_mismatch'        // Requested chain ID doesn't match wallet
+  | 'rate_limited';           // Too many requests from dApp
+
+/**
+ * Request lifecycle states (relay-managed, not exposed to SDK)
+ *
+ * These states are maintained by the relay server for concurrency control.
+ * Documented here for implementation reference only.
+ *
+ * State Transitions:
+ * - created → pending (request delivered to wallet)
+ * - pending → fulfilled (wallet sends success response)
+ * - pending → rejected (wallet sends rejection)
+ * - pending → expired (request TTL exceeded)
+ * - pending → cancelled (dApp cancels request - future feature)
+ */
+export type RequestState =
+  | 'pending'       // Request delivered to wallet, awaiting user action
+  | 'fulfilled'     // Request approved, response sent
+  | 'rejected'      // Request rejected by wallet
+  | 'expired'       // Request TTL exceeded (wallet timeout)
+  | 'cancelled';    // Request cancelled by dApp (future feature, not in v2.1)
+
+/**
+ * Type guard to check if rejection reason is valid
+ */
+export function isValidRejectionReason(reason: string): reason is RequestRejectionReason {
+  const validReasons: RequestRejectionReason[] = [
+    'user_rejected',
+    'request_expired',
+    'invalid_parameters',
+    'unsupported_operation',
+    'insufficient_balance',
+    'security_warning',
+    'wallet_locked',
+    'network_mismatch',
+    'rate_limited',
+  ];
+  return validReasons.includes(reason as RequestRejectionReason);
+}

package/src/types/signing-operations.ts

@@ -0,0 +1,99 @@
+/**
+ * Signing Operations Types for BananaLink Protocol v2.0
+ *
+ * This module defines abstract signing operation types that serve as a base
+ * for concrete signing methods (personal_sign, eth_signTypedData_v4).
+ *
+ * Design: All signing operations share common patterns:
+ * - Data to be signed (format varies by method)
+ * - Chain ID for signature context
+ * - Optional account specification
+ * - Signature result in hex format
+ */
+
+import type { BaseRequestMetadata, BaseResponseMetadata, BaseRejectionMetadata } from './request-lifecycle';
+
+/**
+ * Base signing request
+ * Extended by concrete signing operations (message signing, typed data signing)
+ */
+export interface BaseSigningRequest extends BaseRequestMetadata {
+  /**
+   * The data to be signed
+   * Format depends on signing method:
+   * - personal_sign: UTF-8 string or hex-encoded bytes
+   * - eth_signTypedData_v4: EIP-712 typed data structure
+   */
+  data: unknown;
+
+  /**
+   * Chain ID for signature (EIP-155)
+   * Wallet MUST verify this matches current chain
+   * Used for signature domain separation
+   */
+  chainId: number;
+
+  /**
+   * Signing account address (optional)
+   * If specified, wallet MUST use this address
+   * If omitted, wallet uses currently selected account
+   * Format: 0x-prefixed hex string (42 characters)
+   */
+  account?: string;
+}
+
+/**
+ * Base signing response
+ * Extended by concrete signing response types
+ */
+export interface BaseSigningResponse extends BaseResponseMetadata {
+  /**
+   * The signature produced by wallet
+   * Format: hex-encoded signature (0x-prefixed)
+   * Length depends on signature algorithm:
+   * - ECDSA (secp256k1): 65 bytes = 132 hex chars (+ 0x prefix)
+   */
+  signature: string;
+
+  /**
+   * Address that signed the data
+   * MUST match requested account if specified in request
+   * Format: 0x-prefixed hex string (42 characters)
+   */
+  signerAddress: string;
+}
+
+/**
+ * Signing request rejection
+ * Reuses base rejection metadata (type alias for clarity)
+ */
+export type SigningRejection = BaseRejectionMetadata;
+
+/**
+ * Type guard to validate signature format
+ */
+export function isValidSignature(signature: string): boolean {
+  // Must be 0x-prefixed hex string
+  if (!signature.startsWith('0x')) {
+    return false;
+  }
+
+  // Must be valid hex (no invalid characters)
+  const hexPattern = /^0x[0-9a-fA-F]+$/;
+  if (!hexPattern.test(signature)) {
+    return false;
+  }
+
+  // ECDSA signatures are typically 65 bytes (130 hex chars + 0x)
+  // Allow some flexibility for different signature formats
+  const hexLength = signature.length - 2; // Remove 0x prefix
+  return hexLength >= 128 && hexLength <= 134; // 64-67 bytes
+}
+
+/**
+ * Type guard to validate Ethereum address format
+ */
+export function isValidAddress(address: string): boolean {
+  // Must be 0x-prefixed hex string of exactly 40 hex chars (20 bytes)
+  return /^0x[0-9a-fA-F]{40}$/.test(address);
+}

package/src/types/wallet-messages.ts

@@ -0,0 +1,251 @@
+/**
+ * Wallet message types for BananaLink protocol v2.0
+ * These types define the communication between wallets and the relay server
+ */
+
+import type { EncryptedPayload } from './discovery';
+import type { DAppMetadata, SessionConfig } from './core';
+import type { CloseSessionPayload } from './client-messages';
+import type {
+  RequestFulfilledPayload,
+  RequestRejectedPayload,
+} from './post-auth-operations';
+
+/**
+ * Wallet session claim credential for claiming and reconnection
+ * NEVER forwarded to dApp - relay server only
+ */
+export interface WalletSessionClaim {
+  /**
+   * Unique nonce for this session claim
+   * - Generated once by wallet when claiming session
+   * - Stored locally by wallet for reconnection
+   * - Used by relay to validate session ownership
+   * - Different for each session (no cross-session tracking)
+   */
+  sessionNonce: string;
+
+  /** Claim timestamp (used for replay attack prevention) */
+  timestamp: number;
+}
+
+/**
+ * Wallet message envelope structure
+ * All wallet-to-relay messages use this envelope
+ */
+export interface WalletMessageEnvelope {
+  /** Session identifier */
+  sessionId: string;
+
+  /** Wallet session claim credential - ONLY visible to relay server */
+  walletSessionClaim: WalletSessionClaim;
+
+  /** Actual message payload */
+  payload: WalletMessagePayload;
+}
+
+/**
+ * Claim session payload
+ * Used to claim exclusive ownership of a session
+ */
+export interface ClaimSessionPayload {
+  type: 'claim_session';
+  /** Wallet's public key for ECDH key exchange in format "algorithm:base64_public_key" (e.g., "AES-GCM:...") */
+  walletPublicKey: string;
+}
+
+/**
+ * Prefetch metadata payload
+ * Used to retrieve dApp metadata for user approval
+ */
+export interface PrefetchMetadataPayload {
+  type: 'prefetch_metadata';
+}
+
+/**
+ * Connection rejected payload
+ * Notifies dApp that user rejected connection
+ */
+export interface ConnectionRejectedPayload {
+  type: 'connection_rejected';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Authenticate connection payload
+ * Completes authentication with signed message
+ */
+export interface AuthenticateConnectionPayload {
+  type: 'authenticate_connection';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Wallet reconnect payload
+ * Used to reconnect after network interruption
+ */
+export interface WalletReconnectPayload {
+  type: 'wallet_reconnect';
+}
+
+/**
+ * Union type for all wallet message payloads
+ */
+export type WalletMessagePayload =
+  // Connection flow payloads
+  | ClaimSessionPayload
+  | PrefetchMetadataPayload
+  | ConnectionRejectedPayload
+  | AuthenticateConnectionPayload
+  | WalletReconnectPayload
+  | CloseSessionPayload
+  // Post-authentication operation payloads (v2.1+)
+  | RequestFulfilledPayload
+  | RequestRejectedPayload;
+
+/**
+ * Decrypted rejection data (visible only to dApp after decryption)
+ */
+export interface RejectionData {
+  reason?: string;
+  timestamp: number;
+}
+
+/**
+ * Decrypted authentication data (visible only to dApp after decryption)
+ */
+export interface AuthenticationData {
+  /** Wallet address */
+  address: string;
+
+  /** Signature of the SIWE message */
+  signature: string;
+
+  /** Full SIWE message that was signed */
+  message: string;
+
+  /** Chain ID (EIP-155) */
+  chainId: number;
+
+  /** Network identifier (e.g., "ethereum", "polygon") */
+  network?: string;
+
+  /** Signing algorithm (e.g., "ECDSA", "EdDSA") */
+  signingAlgo?: string;
+
+  /** Optional wallet metadata */
+  walletMetadata?: WalletMetadata;
+}
+
+/**
+ * Wallet metadata
+ */
+export interface WalletMetadata {
+  /** Wallet name */
+  name: string;
+
+  /** Wallet version */
+  version?: string;
+
+  /** Wallet icon URL */
+  icon?: string;
+
+  /** Wallet description */
+  description?: string;
+
+  /** Wallet website URL */
+  url?: string;
+
+  /** Wallet provider type */
+  provider?: string;
+}
+
+/**
+ * Messages sent from relay to dApp (session claim stripped)
+ */
+
+/**
+ * Wallet handshake message
+ * Initiates cryptographic handshake by sharing wallet's public key
+ * and notifying dApp that wallet is reviewing connection
+ */
+export interface WalletHandshakeMessage {
+  type: 'wallet_handshake';
+  status: 'reviewing';
+  /** Wallet's public key in format "algorithm:base64_public_key" (e.g., "AES-GCM:...") */
+  walletPublicKey: string;
+  timestamp: number;
+}
+
+/**
+ * Connection rejected message
+ * Forwards rejection to dApp (encrypted)
+ */
+export interface ConnectionRejectedMessage {
+  type: 'connection_rejected';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Connection authenticated message
+ * Forwards authentication data to dApp (encrypted)
+ */
+export interface ConnectionAuthenticatedMessage {
+  type: 'connection_authenticated';
+  encrypted: EncryptedPayload;
+}
+
+/**
+ * Prefetch metadata response
+ * Returns dApp metadata to wallet
+ */
+export interface PrefetchMetadataResponse {
+  dappMetadata: DAppMetadata;
+  sessionConfig?: SessionConfig;
+}
+
+/**
+ * Union type for relay-to-dApp messages
+ */
+export type RelayToDAppMessage =
+  | WalletHandshakeMessage
+  | ConnectionRejectedMessage
+  | ConnectionAuthenticatedMessage;
+
+/**
+ * Type guards for wallet messages
+ */
+export function isClaimSessionPayload(payload: WalletMessagePayload): payload is ClaimSessionPayload {
+  return payload?.type === 'claim_session';
+}
+
+export function isPrefetchMetadataPayload(payload: WalletMessagePayload): payload is PrefetchMetadataPayload {
+  return payload?.type === 'prefetch_metadata';
+}
+
+export function isConnectionRejectedPayload(payload: WalletMessagePayload): payload is ConnectionRejectedPayload {
+  return payload?.type === 'connection_rejected';
+}
+
+export function isAuthenticateConnectionPayload(payload: WalletMessagePayload): payload is AuthenticateConnectionPayload {
+  return payload?.type === 'authenticate_connection';
+}
+
+export function isWalletReconnectPayload(payload: WalletMessagePayload): payload is WalletReconnectPayload {
+  return payload?.type === 'wallet_reconnect';
+}
+
+/**
+ * Type guards for relay-to-dApp messages
+ */
+export function isWalletHandshakeMessage(message: RelayToDAppMessage): message is WalletHandshakeMessage {
+  return message?.type === 'wallet_handshake';
+}
+
+export function isConnectionRejectedMessage(message: RelayToDAppMessage): message is ConnectionRejectedMessage {
+  return message?.type === 'connection_rejected';
+}
+
+export function isConnectionAuthenticatedMessage(message: RelayToDAppMessage): message is ConnectionAuthenticatedMessage {
+  return message?.type === 'connection_authenticated';
+}

package/src/utils/client-session-claim.ts

@@ -0,0 +1,188 @@
+/**
+ * Client session claim utilities for BananaLink protocol v2.0
+ * Implements secure client session ownership and reconnection logic
+ */
+
+import type { ClientSessionClaim, ClientMessageEnvelope } from '../types/client-messages';
+
+/**
+ * Client session claim storage interface
+ * Implementations should provide secure storage for client session claims
+ */
+export interface ClientSessionClaimStorage {
+  store(sessionId: string, claim: ClientSessionClaim): Promise<void>;
+  retrieve(sessionId: string): Promise<ClientSessionClaim | null>;
+  remove(sessionId: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/**
+ * Client session claim manager for handling claim generation and validation
+ */
+export class ClientSessionClaimManager {
+  constructor(private storage: ClientSessionClaimStorage) {}
+
+  /**
+   * Generate a new client session claim with provided nonce
+   * @param sessionId - Session identifier
+   * @param claimNonce - Pre-generated cryptographically secure nonce (use @bananalink-sdk/crypto)
+   * @returns Generated client session claim
+   */
+  async generateClaim(sessionId: string, claimNonce: string): Promise<ClientSessionClaim> {
+    const claim: ClientSessionClaim = {
+      claimNonce,
+      timestamp: Date.now(),
+    };
+
+    // Store the claim for future reconnection
+    await this.storage.store(sessionId, claim);
+
+    return claim;
+  }
+
+  /**
+   * Retrieve an existing client session claim
+   * @param sessionId - Session identifier
+   * @returns Stored client session claim or null if not found
+   */
+  async getClaim(sessionId: string): Promise<ClientSessionClaim | null> {
+    return this.storage.retrieve(sessionId);
+  }
+
+  /**
+   * Validate a client session claim for reconnection
+   * @param claim - Claim to validate
+   * @param storedClaim - Previously stored claim
+   * @returns Validation result
+   */
+  validateReconnectionClaim(
+    claim: ClientSessionClaim,
+    storedClaim: ClientSessionClaim
+  ): { valid: boolean; reason?: string } {
+    // Check nonce match
+    if (claim.claimNonce !== storedClaim.claimNonce) {
+      return {
+        valid: false,
+        reason: 'Client claim nonce mismatch - invalid reconnection attempt',
+      };
+    }
+
+    // Check timestamp validity (prevent very old reconnection attempts)
+    const MAX_RECONNECTION_AGE = 24 * 60 * 60 * 1000; // 24 hours
+    const claimAge = Date.now() - claim.timestamp;
+    if (claimAge > MAX_RECONNECTION_AGE) {
+      return {
+        valid: false,
+        reason: 'Client session claim too old - please create a new session',
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Remove a client session claim (on session end)
+   * @param sessionId - Session identifier
+   */
+  async removeClaim(sessionId: string): Promise<void> {
+    await this.storage.remove(sessionId);
+  }
+
+  /**
+   * Clear all stored claims
+   */
+  async clearAllClaims(): Promise<void> {
+    await this.storage.clear();
+  }
+}
+
+// NOTE: Nonce generation moved to @bananalink-sdk/crypto package to avoid circular dependencies
+// SDKs should use crypto.generateClientClaimNonce() before creating client session claims
+
+/**
+ * Create a client message envelope with session claim
+ * @param sessionId - Session identifier
+ * @param claim - Client session claim
+ * @param payload - Message payload
+ * @returns Complete client message envelope
+ */
+export function createClientMessageEnvelope(
+  sessionId: string,
+  claim: ClientSessionClaim,
+  payload: ClientMessageEnvelope['payload']
+): ClientMessageEnvelope {
+  return {
+    sessionId,
+    clientSessionClaim: claim,
+    payload,
+  };
+}
+
+/**
+ * Strip client session claim from client message for forwarding
+ * @param envelope - Original client message envelope
+ * @returns Message without client session claim
+ */
+export function stripClientSessionClaim(
+  envelope: ClientMessageEnvelope
+): Omit<ClientMessageEnvelope, 'clientSessionClaim'> {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { clientSessionClaim, ...messageWithoutClaim } = envelope;
+  return messageWithoutClaim;
+}
+
+/**
+ * Validate client session claim timestamp for replay attack prevention
+ * @param timestamp - Claim timestamp
+ * @param maxAge - Maximum age in milliseconds (default: 30 seconds)
+ * @returns True if timestamp is within valid range
+ */
+export function validateClientClaimTimestamp(
+  timestamp: number,
+  maxAge: number = 30 * 1000
+): boolean {
+  const now = Date.now();
+  const age = Math.abs(now - timestamp);
+  return age <= maxAge;
+}
+
+/**
+ * Validate client message envelope
+ * @param envelope - Message envelope to validate
+ * @returns Validation result
+ */
+export function validateClientMessageEnvelope(
+  envelope: ClientMessageEnvelope
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Check required fields
+  if (!envelope.sessionId) {
+    errors.push('Missing session ID');
+  }
+
+  if (!envelope.clientSessionClaim) {
+    errors.push('Missing client session claim');
+  } else {
+    // Validate claim structure
+    if (!envelope.clientSessionClaim.claimNonce) {
+      errors.push('Missing claim nonce in client session claim');
+    }
+    if (!envelope.clientSessionClaim.timestamp) {
+      errors.push('Missing timestamp in client session claim');
+    } else if (!validateClientClaimTimestamp(envelope.clientSessionClaim.timestamp)) {
+      errors.push('Client session claim timestamp is too old or invalid');
+    }
+  }
+
+  if (!envelope.payload) {
+    errors.push('Missing message payload');
+  } else if (!envelope.payload.type) {
+    errors.push('Missing payload type');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}