@bananalink-sdk/protocol 1.2.7

package/src/utils/url-encoding.ts

@@ -0,0 +1,144 @@
+import type { QRPayload } from '../types/discovery';
+import { DEEPLINK_SCHEME } from '../constants';
+import { compressPublicKey } from './public-keys';
+
+/**
+ * Provider shortcodes for compact URLs
+ */
+const PROVIDER_SHORTCODES: Record<string, string> = {
+  'uwebsockets': 'u', // Legacy - API may still return this
+  'websocket': 'w',
+  'pusher': 'p',
+  'ably': 'a',
+};
+
+/**
+ * Production relay URLs that should be omitted in compact format (most common case)
+ */
+const PRODUCTION_RELAY_URLS = [
+  'wss://relay.banana.link/v1',
+  'https://relay.banana.link/v1',
+];
+
+/**
+ * Environment shortcodes for non-production relay URLs
+ */
+const RELAY_SHORTCODES: Record<string, string> = {
+  'wss://relay.dev.banana.link/v1': 'd',
+  'https://relay.dev.banana.link/v1': 'd',
+  'wss://relay.staging.banana.link/v1': 's', // Future staging environment
+  'https://relay.staging.banana.link/v1': 's',
+};
+
+/**
+ * Safely encode a URL parameter value
+ * Uses encodeURIComponent to handle special characters like +, /, =
+ */
+export function encodeUrlParameter(value: string): string {
+  return encodeURIComponent(value);
+}
+
+/**
+ * Build a query string with properly encoded parameters
+ */
+export function buildQueryString(params: Record<string, string | undefined>): string {
+  const pairs: string[] = [];
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      pairs.push(`${encodeUrlParameter(key)}=${encodeUrlParameter(value)}`);
+    }
+  }
+
+  return pairs.join('&');
+}
+
+/**
+ * Create a compact deep link URL with shortened parameters
+ * Uses single-letter parameters to minimize QR code size
+ */
+export function encodeCompactConnectionString(payload: QRPayload): string {
+  const params: Record<string, string | undefined> = {
+    s: payload.sessionId, // sessionId -> s
+    k: compressPublicKey(payload.publicKey), // publicKey -> k (compressed)
+  };
+
+  // Add optional parameters with shortcodes
+  if (payload.providerId) {
+    params.p = PROVIDER_SHORTCODES[payload.providerId] || payload.providerId;
+  }
+
+  // Handle relay URL compression:
+  // - Production: omit entirely (most common case)
+  // - Development/Staging: use shortcode (r=d, r=s)
+  // - Custom: use full URL
+  if (payload.relayUrl) {
+    if (PRODUCTION_RELAY_URLS.includes(payload.relayUrl)) {
+      // Production relay - omit parameter entirely for maximum compression
+      // This will be the most common case, so QR codes will be smallest
+    } else if (RELAY_SHORTCODES[payload.relayUrl]) {
+      // Known environment (dev/staging) - use shortcode
+      params.r = RELAY_SHORTCODES[payload.relayUrl];
+    } else {
+      // Custom relay URL - include full URL
+      params.r = payload.relayUrl;
+    }
+  }
+
+  const queryString = buildQueryString(params);
+  return `${DEEPLINK_SCHEME}://connect?${queryString}`;
+}
+
+/**
+ * Create a deep link URL with properly encoded parameters
+ * Uses full parameter names for readability
+ */
+export function encodeConnectionString(payload: QRPayload): string {
+  const params: Record<string, string | undefined> = {
+    sessionId: payload.sessionId,
+    publicKey: payload.publicKey,
+  };
+
+  // Add optional parameters
+  if (payload.providerId) {
+    params.providerId = payload.providerId;
+  }
+
+  if (payload.relayUrl) {
+    params.relay = payload.relayUrl;
+  }
+
+  const queryString = buildQueryString(params);
+  return `${DEEPLINK_SCHEME}://connect?${queryString}`;
+}
+
+/**
+ * Create a universal link (HTTPS) with properly encoded parameters
+ */
+export function encodeUniversalLink(payload: QRPayload, options: {
+  baseUrl?: string;
+  fallbackUrl?: string;
+} = {}): string {
+  const {
+    baseUrl = 'https://banana.link',
+    fallbackUrl = 'https://banana.link/download',
+  } = options;
+
+  const params: Record<string, string | undefined> = {
+    sessionId: payload.sessionId,
+    key: payload.publicKey, // Use 'key' instead of 'publicKey' for universal links
+    fallback: fallbackUrl,
+  };
+
+  // Add optional parameters
+  if (payload.providerId) {
+    params.provider = payload.providerId;
+  }
+
+  if (payload.relayUrl) {
+    params.relay = payload.relayUrl;
+  }
+
+  const queryString = buildQueryString(params);
+  return `${baseUrl}/connect?${queryString}`;
+}

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

@@ -0,0 +1,188 @@
+/**
+ * Session claiming mechanism utilities for BananaLink protocol v2.0
+ * Implements secure session ownership and reconnection logic
+ */
+
+import type { WalletSessionClaim, WalletMessageEnvelope } from '../types/wallet-messages';
+
+/**
+ * Wallet session claim storage interface
+ * Implementations should provide secure storage for wallet session claims
+ */
+export interface WalletSessionClaimStorage {
+  store(sessionId: string, claim: WalletSessionClaim): Promise<void>;
+  retrieve(sessionId: string): Promise<WalletSessionClaim | null>;
+  remove(sessionId: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/**
+ * Wallet session claim manager for handling claim generation and validation
+ */
+export class WalletSessionClaimManager {
+  constructor(private storage: WalletSessionClaimStorage) {}
+
+  /**
+   * Generate a new wallet session claim with provided nonce
+   * @param sessionId - Session identifier
+   * @param sessionNonce - Pre-generated cryptographically secure nonce (use @bananalink-sdk/crypto)
+   * @returns Generated wallet session claim
+   */
+  async generateClaim(sessionId: string, sessionNonce: string): Promise<WalletSessionClaim> {
+    const claim: WalletSessionClaim = {
+      sessionNonce,
+      timestamp: Date.now(),
+    };
+
+    // Store the claim for future reconnection
+    await this.storage.store(sessionId, claim);
+
+    return claim;
+  }
+
+  /**
+   * Retrieve an existing wallet session claim
+   * @param sessionId - Session identifier
+   * @returns Stored wallet session claim or null if not found
+   */
+  async getClaim(sessionId: string): Promise<WalletSessionClaim | null> {
+    return this.storage.retrieve(sessionId);
+  }
+
+  /**
+   * Validate a wallet session claim for reconnection
+   * @param claim - Claim to validate
+   * @param storedClaim - Previously stored claim
+   * @returns Validation result
+   */
+  validateReconnectionClaim(
+    claim: WalletSessionClaim,
+    storedClaim: WalletSessionClaim
+  ): { valid: boolean; reason?: string } {
+    // Check nonce match
+    if (claim.sessionNonce !== storedClaim.sessionNonce) {
+      return {
+        valid: false,
+        reason: 'Session 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: 'Session claim too old - please create a new session',
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Remove a wallet 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.generateSessionNonce() before creating session claims
+
+/**
+ * Create a wallet message envelope with wallet session claim
+ * @param sessionId - Session identifier
+ * @param claim - Wallet session claim
+ * @param payload - Message payload
+ * @returns Complete wallet message envelope
+ */
+export function createWalletMessageEnvelope(
+  sessionId: string,
+  claim: WalletSessionClaim,
+  payload: WalletMessageEnvelope['payload']
+): WalletMessageEnvelope {
+  return {
+    sessionId,
+    walletSessionClaim: claim,
+    payload,
+  };
+}
+
+/**
+ * Strip wallet session claim from wallet message for forwarding to dApp
+ * @param envelope - Original wallet message envelope
+ * @returns Message without wallet session claim
+ */
+export function stripWalletSessionClaim(
+  envelope: WalletMessageEnvelope
+): Omit<WalletMessageEnvelope, 'walletSessionClaim'> {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { walletSessionClaim, ...messageWithoutClaim } = envelope;
+  return messageWithoutClaim;
+}
+
+/**
+ * Validate 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 validateClaimTimestamp(
+  timestamp: number,
+  maxAge: number = 30 * 1000
+): boolean {
+  const now = Date.now();
+  const age = Math.abs(now - timestamp);
+  return age <= maxAge;
+}
+
+/**
+ * Validate wallet message envelope
+ * @param envelope - Message envelope to validate
+ * @returns Validation result
+ */
+export function validateWalletMessageEnvelope(
+  envelope: WalletMessageEnvelope
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Check required fields
+  if (!envelope.sessionId) {
+    errors.push('Missing session ID');
+  }
+
+  if (!envelope.walletSessionClaim) {
+    errors.push('Missing wallet session claim');
+  } else {
+    // Validate claim structure
+    if (!envelope.walletSessionClaim.sessionNonce) {
+      errors.push('Missing session nonce in wallet session claim');
+    }
+    if (!envelope.walletSessionClaim.timestamp) {
+      errors.push('Missing timestamp in wallet session claim');
+    } else if (!validateClaimTimestamp(envelope.walletSessionClaim.timestamp)) {
+      errors.push('Wallet 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,
+  };
+}

package/src/validation-export.ts

@@ -0,0 +1,32 @@
+/**
+ * Full Zod validation export
+ *
+ * Complete runtime validation with Zod schemas (~48KB bundle)
+ * For lightweight validation, use @bananalink-sdk/protocol/validators
+ */
+
+// Re-export all schemas
+export * from './schemas';
+
+// Re-export lightweight validators for convenience
+// Note: EncryptedPayload type conflict resolved by explicit schema export
+export {
+  isValidAddress,
+  isValidUrl,
+  isValidTimestamp,
+  isValidChainId,
+  isValidNonce,
+  isValidSessionId,
+  isValidBase64,
+  isValidHex,
+  isValidMessageType,
+  isValidEncryptionAlgorithm,
+  isValidDomain,
+  isValidPublicKey,
+  isValidEncryptedPayload,
+  isValidSIWEMessage,
+  createValidationResult,
+  hasRequiredFields,
+  type ValidationResult,
+  type SIWEMessage
+} from './validators';

package/src/validators/index.ts

@@ -0,0 +1,222 @@
+/**
+ * Lightweight validation utilities for BananaLink protocol types
+ *
+ * Zero dependencies, minimal bundle size (~3KB)
+ * Suitable for browsers, React Native, and Node.js
+ *
+ * For full Zod-based validation, use: @bananalink-sdk/protocol/validation
+ */
+
+/**
+ * Validate Ethereum address format (0x + 40 hex characters)
+ */
+export function isValidAddress(address: unknown): address is string {
+  return typeof address === 'string' && /^0x[0-9a-fA-F]{40}$/.test(address);
+}
+
+/**
+ * Validate URL format
+ */
+export function isValidUrl(url: unknown): url is string {
+  if (typeof url !== 'string') return false;
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate ISO 8601 timestamp format
+ */
+export function isValidTimestamp(timestamp: unknown): timestamp is string {
+  if (typeof timestamp !== 'string') return false;
+  try {
+    const date = new Date(timestamp);
+    return !isNaN(date.getTime()) && timestamp === date.toISOString();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate chain ID (positive integer)
+ */
+export function isValidChainId(chainId: unknown): chainId is number {
+  return typeof chainId === 'number' && Number.isInteger(chainId) && chainId > 0;
+}
+
+/**
+ * Validate nonce format (64 hex characters = 32 bytes)
+ * Protocol v2.0 standard
+ */
+export function isValidNonce(nonce: unknown): nonce is string {
+  return typeof nonce === 'string' && /^[a-fA-F0-9]{64}$/.test(nonce);
+}
+
+/**
+ * Validate session ID format (UUID v4)
+ */
+export function isValidSessionId(sessionId: unknown): sessionId is string {
+  return (
+    typeof sessionId === 'string' &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(sessionId)
+  );
+}
+
+/**
+ * Validate base64 string format
+ * Accepts standard base64 (with padding) and base64url variants
+ */
+export function isValidBase64(str: unknown): str is string {
+  if (typeof str !== 'string' || str.length === 0) return false;
+
+  // RFC 4648 base64 pattern: A-Z, a-z, 0-9, +, /, = (padding)
+  // Also accepts base64url variant: A-Z, a-z, 0-9, -, _
+  const base64Pattern = /^[A-Za-z0-9+/\-_]+(={0,2})$/;
+
+  if (!base64Pattern.test(str)) return false;
+
+  // Validate padding - must be 0, 1, or 2 '=' characters at the end
+  // Length must be multiple of 4 for standard base64 with padding
+  const paddingMatch = str.match(/=*$/);
+  const padding = paddingMatch ? paddingMatch[0].length : 0;
+
+  // For base64url (no padding) or standard base64 (proper padding)
+  return padding === 0 || (padding <= 2 && (str.length % 4 === 0));
+}
+
+/**
+ * Validate hex string format
+ */
+export function isValidHex(hex: unknown): hex is string {
+  return typeof hex === 'string' && /^(0x)?[0-9a-fA-F]+$/.test(hex);
+}
+
+/**
+ * Validation result with detailed error information
+ */
+export interface ValidationResult<T = unknown> {
+  valid: boolean;
+  error?: string;
+  data?: T;
+}
+
+/**
+ * Validate message type enum
+ */
+export function isValidMessageType(type: unknown): type is 'auth' | 'tx' | 'sign' {
+  return type === 'auth' || type === 'tx' || type === 'sign';
+}
+
+/**
+ * Validate encryption algorithm
+ */
+export function isValidEncryptionAlgorithm(algo: unknown): algo is 'AES-GCM' | 'plaintext' {
+  return algo === 'AES-GCM' || algo === 'plaintext';
+}
+
+/**
+ * Validate domain name format
+ */
+export function isValidDomain(domain: unknown): domain is string {
+  if (typeof domain !== 'string' || domain.length === 0) return false;
+  // Basic domain validation (not comprehensive, but sufficient for protocol)
+  return /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(
+    domain
+  );
+}
+
+/**
+ * Validate public key format (algorithm:base64)
+ */
+export function isValidPublicKey(publicKey: unknown): publicKey is string {
+  if (typeof publicKey !== 'string') return false;
+  const parts = publicKey.split(':');
+  if (parts.length !== 2) return false;
+  const [algorithm, key] = parts;
+  return (
+    (algorithm === 'AES-GCM' || algorithm === 'cleartext') &&
+    (algorithm === 'cleartext' || isValidBase64(key))
+  );
+}
+
+/**
+ * Validate encrypted payload structure
+ */
+export interface EncryptedPayload {
+  iv: string;
+  ciphertext: string;
+  mac: string;
+}
+
+export function isValidEncryptedPayload(payload: unknown): payload is EncryptedPayload {
+  if (!payload || typeof payload !== 'object') return false;
+  const p = payload as Record<string, unknown>;
+  return (
+    isValidBase64(p.iv) &&
+    isValidBase64(p.ciphertext) &&
+    isValidBase64(p.mac)
+  );
+}
+
+/**
+ * Create a validation result
+ */
+export function createValidationResult<T = unknown>(
+  valid: boolean,
+  data?: T,
+  error?: string
+): ValidationResult<T> {
+  if (valid) {
+    return { valid: true, data };
+  }
+  return { valid: false, error };
+}
+
+/**
+ * Validate required fields are present and non-empty
+ */
+export function hasRequiredFields<T extends object>(
+  obj: unknown,
+  fields: (keyof T)[]
+): obj is T {
+  if (!obj || typeof obj !== 'object') return false;
+  const o = obj as Record<string, unknown>;
+  return fields.every(
+    (field) =>
+      field in o &&
+      o[field as string] !== null &&
+      o[field as string] !== undefined &&
+      o[field as string] !== ''
+  );
+}
+
+/**
+ * Validate SIWE message structure (minimal check)
+ */
+export interface SIWEMessage {
+  domain: string;
+  address: string;
+  uri: string;
+  version: string;
+  chainId: number;
+  nonce: string;
+  issuedAt: string;
+}
+
+export function isValidSIWEMessage(message: unknown): message is SIWEMessage {
+  if (!message || typeof message !== 'object') return false;
+  const m = message as Record<string, unknown>;
+
+  return (
+    isValidDomain(m.domain) &&
+    isValidAddress(m.address) &&
+    isValidUrl(m.uri) &&
+    m.version === '1' &&
+    isValidChainId(m.chainId) &&
+    isValidNonce(m.nonce) &&
+    isValidTimestamp(m.issuedAt)
+  );
+}

package/src/validators-export.ts

@@ -0,0 +1,8 @@
+/**
+ * Lightweight validators export
+ *
+ * Zero-dependency validation utilities (~3KB bundle)
+ * For Zod-based validation, use @bananalink-sdk/protocol/validation
+ */
+
+export * from './validators';