@bananalink-sdk/protocol 1.2.7

package/src/utils/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Protocol utility functions
+ *
+ * This module provides utility functions that are specific to the BananaLink protocol.
+ * SDK-specific utilities are implemented in their respective packages.
+ */
+
+import { generateUUID } from '../crypto/utils';
+
+/**
+ * Generate a cryptographically secure session ID in RFC 4122 UUID v4 format
+ *
+ * This function delegates to the protocol crypto layer for mobile-safe UUID generation.
+ * For direct access to UUID generation, prefer importing from @bananalink-sdk/protocol/crypto.
+ *
+ * @returns UUID v4 string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+ *
+ * @example
+ * const sessionId = generateSessionId();
+ * // => "a3bb189e-8bf9-4bdc-9f16-9f48a6a1e3e7"
+ */
+export function generateSessionId(): string {
+  return generateUUID();
+}
+
+// Protocol-specific utility that might be needed across packages
+export function isValidProtocolVersion(version: string): boolean {
+  // Only support version "1" for now
+  return version === '1';
+}
+
+// Protocol-specific session ID validation
+export function isValidSessionId(sessionId: string): boolean {
+  // Session IDs should be valid UUIDs
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(sessionId);
+}
+
+// Export public key compression utilities
+export * from './public-keys';
+
+// Export URL encoding and decoding utilities
+export * from './url-encoding';
+export * from './url-decoding';
+
+// Note: SIWE utilities have been moved to '@bananalink-sdk/protocol/siwe'
+// For ERC-4361 message construction and validation, import from '@bananalink-sdk/protocol/siwe'
+// Type-only definitions (SIWEFields, SIWEMessageOptions) remain available from main export
+
+// Export wallet session claiming utilities
+export * from './wallet-session-claim';
+
+// Export client session claiming utilities
+export * from './client-session-claim';

package/src/utils/public-keys.ts

@@ -0,0 +1,49 @@
+/**
+ * Public key compression utilities for compact URL encoding
+ *
+ * These utilities convert public keys between standard base64 format
+ * and compact base64url format for use in QR codes and URLs.
+ */
+
+/**
+ * Compress a public key for compact URLs
+ * Removes AES-GCM: prefix and uses base64url without padding
+ *
+ * @param publicKey - Public key in format "AES-GCM:base64string" or "base64string"
+ * @returns Compressed public key in base64url format without padding
+ */
+export function compressPublicKey(publicKey: string): string {
+  // Remove AES-GCM: prefix if present
+  const keyWithoutPrefix = publicKey.startsWith('AES-GCM:')
+    ? publicKey.slice(8)
+    : publicKey;
+
+  // Convert base64 to base64url (replace + with -, / with _, remove padding)
+  return keyWithoutPrefix
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * Decompress a public key from compact format
+ * Adds back AES-GCM: prefix and restores base64 padding
+ *
+ * @param compressedKey - Compressed public key in base64url format
+ * @returns Public key in format "AES-GCM:base64string"
+ */
+export function decompressPublicKey(compressedKey: string): string {
+  // Convert base64url back to base64
+  let base64Key = compressedKey
+    .replace(/-/g, '+')
+    .replace(/_/g, '/');
+
+  // Add padding if needed
+  const padding = base64Key.length % 4;
+  if (padding > 0) {
+    base64Key += '='.repeat(4 - padding);
+  }
+
+  // Add AES-GCM prefix if not already present
+  return base64Key.startsWith('AES-GCM:') ? base64Key : `AES-GCM:${base64Key}`;
+}

package/src/utils/siwe.ts

@@ -0,0 +1,362 @@
+/**
+ * SIWE (Sign-In with Ethereum) message construction utilities
+ * Implements ERC-4361 compliant message formatting
+ */
+
+import type { SIWEFields } from '../types/core';
+
+/**
+ * Options for SIWE message construction
+ */
+export interface SIWEMessageOptions extends Partial<SIWEFields> {
+  domain: string;
+  address: string;
+  uri: string;
+  chainId: number;
+  nonce: string;
+  statement?: string;
+}
+
+/**
+ * Construct a SIWE message according to ERC-4361 specification
+ * @param options - SIWE message options
+ * @returns Formatted SIWE message string
+ */
+export function constructSIWEMessage(options: SIWEMessageOptions): string {
+  const {
+    domain,
+    address,
+    statement,
+    uri,
+    version = '1',
+    chainId,
+    nonce,
+    issuedAt = new Date().toISOString(),
+    expirationTime,
+    notBefore,
+    requestId,
+    resources,
+    scheme,
+  } = options;
+
+  // Validate required fields
+  if (!domain || !address || !uri || !chainId || !nonce) {
+    throw new Error('Missing required SIWE fields: domain, address, uri, chainId, nonce');
+  }
+
+  // Validate address format
+  if (!isValidEthereumAddress(address)) {
+    throw new Error('Invalid Ethereum address format');
+  }
+
+  // Construct message parts according to ERC-4361
+  const parts: string[] = [];
+
+  // Header: domain wants you to sign in
+  const header = scheme ? `${scheme}://${domain}` : domain;
+  parts.push(`${header} wants you to sign in with your Ethereum account:`);
+  parts.push(address);
+  parts.push(''); // Empty line
+
+  // Optional statement
+  if (statement) {
+    parts.push(statement);
+    parts.push(''); // Empty line
+  }
+
+  // Required fields
+  parts.push(`URI: ${uri}`);
+  parts.push(`Version: ${version}`);
+  parts.push(`Chain ID: ${chainId}`);
+  parts.push(`Nonce: ${nonce}`);
+  parts.push(`Issued At: ${issuedAt}`);
+
+  // Optional fields
+  if (expirationTime) {
+    parts.push(`Expiration Time: ${expirationTime}`);
+  }
+  if (notBefore) {
+    parts.push(`Not Before: ${notBefore}`);
+  }
+  if (requestId) {
+    parts.push(`Request ID: ${requestId}`);
+  }
+
+  // Resources
+  if (resources && resources.length > 0) {
+    parts.push('Resources:');
+    resources.forEach(resource => {
+      parts.push(`- ${resource}`);
+    });
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Parse a SIWE message string into its component fields
+ * @param message - SIWE message string
+ * @returns Parsed SIWE fields
+ */
+export function parseSIWEMessage(message: string): SIWEFields {
+  const lines = message.split('\n');
+
+  if (lines.length < 6) {
+    throw new Error('Invalid SIWE message format: insufficient lines');
+  }
+
+  // Parse header
+  const headerMatch = lines[0].match(/^((?<scheme>[^:]+):\/\/)?(?<domain>.+) wants you to sign in with your Ethereum account:$/);
+  if (!headerMatch) {
+    throw new Error('Invalid SIWE message header');
+  }
+
+  const fields: SIWEFields = {
+    scheme: headerMatch.groups?.scheme,
+    domain: headerMatch.groups?.domain || '',
+    address: lines[1],
+    statement: undefined,
+    uri: '',
+    version: '1',
+    chainId: 0,
+    nonce: '',
+    issuedAt: '',
+  };
+
+  // Find where the required fields start
+  let fieldIndex = 2;
+
+  // Check for optional statement (non-empty lines before URI)
+  const statementLines: string[] = [];
+  while (fieldIndex < lines.length && !lines[fieldIndex].startsWith('URI: ')) {
+    if (lines[fieldIndex]) {
+      statementLines.push(lines[fieldIndex]);
+    }
+    fieldIndex++;
+  }
+
+  if (statementLines.length > 0) {
+    // Remove trailing empty line if present
+    if (statementLines[statementLines.length - 1] === '') {
+      statementLines.pop();
+    }
+    fields.statement = statementLines.join('\n');
+  }
+
+  // Parse required and optional fields
+  for (let i = fieldIndex; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (line.startsWith('URI: ')) {
+      fields.uri = line.substring(5);
+    } else if (line.startsWith('Version: ')) {
+      fields.version = line.substring(9);
+    } else if (line.startsWith('Chain ID: ')) {
+      fields.chainId = parseInt(line.substring(10), 10);
+    } else if (line.startsWith('Nonce: ')) {
+      fields.nonce = line.substring(7);
+    } else if (line.startsWith('Issued At: ')) {
+      fields.issuedAt = line.substring(11);
+    } else if (line.startsWith('Expiration Time: ')) {
+      fields.expirationTime = line.substring(17);
+    } else if (line.startsWith('Not Before: ')) {
+      fields.notBefore = line.substring(12);
+    } else if (line.startsWith('Request ID: ')) {
+      fields.requestId = line.substring(12);
+    } else if (line === 'Resources:') {
+      // Parse resources list
+      fields.resources = [];
+      i++;
+      while (i < lines.length && lines[i].startsWith('- ')) {
+        fields.resources.push(lines[i].substring(2));
+        i++;
+      }
+      i--; // Adjust for the outer loop increment
+    }
+  }
+
+  // Validate required fields
+  if (!fields.uri || !fields.nonce || !fields.chainId || !fields.issuedAt) {
+    throw new Error('Missing required SIWE fields in message');
+  }
+
+  return fields;
+}
+
+/**
+ * Create a BananaLink-specific SIWE message for session authentication
+ * @param sessionId - Session identifier
+ * @param address - Ethereum address
+ * @param domain - dApp domain
+ * @param chainId - Chain ID
+ * @param nonce - Session nonce
+ * @param statement - Optional custom statement
+ * @returns Formatted SIWE message
+ */
+export function createBananaLinkSIWEMessage(
+  sessionId: string,
+  address: string,
+  domain: string,
+  chainId: number,
+  nonce: string,
+  statement?: string
+): string {
+  return constructSIWEMessage({
+    domain,
+    address,
+    statement: statement || `Sign in to ${domain}`,
+    uri: `bananalink://session/${sessionId}`,
+    chainId,
+    nonce,
+    version: '1',
+    issuedAt: new Date().toISOString(),
+  });
+}
+
+/**
+ * Validate an Ethereum address format
+ * @param address - Address to validate
+ * @returns True if valid Ethereum address
+ */
+export function isValidEthereumAddress(address: string): boolean {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+// NOTE: Nonce generation moved to @bananalink-sdk/crypto package to avoid circular dependencies
+// SDKs should use crypto package to generate nonces before constructing SIWE messages
+
+/**
+ * Validate SIWE message timestamp
+ * @param timestamp - ISO 8601 timestamp
+ * @param maxAge - Maximum age in milliseconds (default: 5 minutes)
+ * @returns True if timestamp is within valid range
+ */
+export function validateSIWETimestamp(timestamp: string, maxAge: number = 5 * 60 * 1000): boolean {
+  try {
+    const messageTime = new Date(timestamp).getTime();
+    const now = Date.now();
+    const age = Math.abs(now - messageTime);
+    return age <= maxAge;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate SIWE message expiration
+ * @param expirationTime - Optional expiration timestamp
+ * @returns True if message has not expired
+ */
+export function validateSIWEExpiration(expirationTime?: string): boolean {
+  // Empty string should be treated as invalid (check before falsy check)
+  if (expirationTime === '') {
+    return false;
+  }
+
+  if (!expirationTime) {
+    return true; // No expiration set (undefined or null)
+  }
+
+  try {
+    const expiry = new Date(expirationTime).getTime();
+    // Check for Invalid Date
+    if (isNaN(expiry)) {
+      return false;
+    }
+    return Date.now() < expiry;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate SIWE message not-before time
+ * @param notBefore - Optional not-before timestamp
+ * @returns True if current time is after not-before time
+ */
+export function validateSIWENotBefore(notBefore?: string): boolean {
+  // Empty string should be treated as invalid (check before falsy check)
+  if (notBefore === '') {
+    return false;
+  }
+
+  if (!notBefore) {
+    return true; // No not-before restriction (undefined or null)
+  }
+
+  try {
+    const notBeforeTime = new Date(notBefore).getTime();
+    // Check for Invalid Date
+    if (isNaN(notBeforeTime)) {
+      return false;
+    }
+    return Date.now() >= notBeforeTime;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Comprehensive SIWE message validation
+ * @param fields - SIWE fields to validate
+ * @param options - Validation options
+ * @returns Validation result with any errors
+ */
+export function validateSIWEMessage(
+  fields: SIWEFields,
+  options: {
+    expectedDomain?: string;
+    expectedChainId?: number;
+    maxAge?: number;
+  } = {}
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Check required fields
+  if (!fields.domain) errors.push('Missing domain');
+  if (!fields.address) errors.push('Missing address');
+  if (!fields.uri) errors.push('Missing URI');
+  if (!fields.chainId) errors.push('Missing chain ID');
+  if (!fields.nonce) errors.push('Missing nonce');
+  if (!fields.issuedAt) errors.push('Missing issued at timestamp');
+
+  // Validate address format
+  if (fields.address && !isValidEthereumAddress(fields.address)) {
+    errors.push('Invalid Ethereum address format');
+  }
+
+  // Validate version
+  if (fields.version !== '1') {
+    errors.push(`Invalid SIWE version: ${fields.version} (must be 1)`);
+  }
+
+  // Domain validation
+  if (options.expectedDomain && fields.domain !== options.expectedDomain) {
+    errors.push(`Domain mismatch: expected ${options.expectedDomain}, got ${fields.domain}`);
+  }
+
+  // Chain ID validation
+  if (options.expectedChainId && fields.chainId !== options.expectedChainId) {
+    errors.push(`Chain ID mismatch: expected ${options.expectedChainId}, got ${fields.chainId}`);
+  }
+
+  // Timestamp validation
+  if (!validateSIWETimestamp(fields.issuedAt, options.maxAge)) {
+    errors.push('Message timestamp is too old or invalid');
+  }
+
+  // Expiration validation
+  if (!validateSIWEExpiration(fields.expirationTime)) {
+    errors.push('Message has expired');
+  }
+
+  // Not-before validation
+  if (!validateSIWENotBefore(fields.notBefore)) {
+    errors.push('Message is not yet valid (not-before time not reached)');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/utils/url-decoding.ts

@@ -0,0 +1,126 @@
+import type { QRPayload } from '../types/discovery';
+import { decompressPublicKey } from './public-keys';
+
+/**
+ * Provider shortcodes reverse mapping for compact URL decoding
+ */
+const PROVIDER_SHORTCODES_REVERSE: Record<string, string> = {
+  'u': 'websocket', // Decode legacy 'u' to new 'websocket' name
+  'w': 'websocket',
+  'p': 'pusher',
+  'a': 'ably',
+};
+
+/**
+ * Environment shortcodes reverse mapping for relay URL decoding
+ */
+const RELAY_SHORTCODES_REVERSE: Record<string, string> = {
+  'd': 'wss://relay.dev.banana.link/v1',
+  's': 'wss://relay.staging.banana.link/v1',
+};
+
+/**
+ * Safely decode a URL parameter value
+ * Uses decodeURIComponent to restore special characters
+ */
+export function decodeUrlParameter(value: string): string {
+  return decodeURIComponent(value);
+}
+
+/**
+ * Parse a query string with properly decoded parameters
+ */
+export function parseQueryString(query: string): Record<string, string> {
+  const params: Record<string, string> = {};
+
+  // Remove leading ? if present
+  const cleanQuery = query.startsWith('?') ? query.slice(1) : query;
+
+  if (!cleanQuery) {
+    return params;
+  }
+
+  for (const pair of cleanQuery.split('&')) {
+    const [key, ...valueParts] = pair.split('=');
+    if (key) {
+      const value = valueParts.join('='); // Handle values that contain =
+      params[decodeUrlParameter(key)] = decodeUrlParameter(value);
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Parse a connection string and extract the QRPayload with proper decoding
+ * Supports both full format and compact format
+ */
+export function decodeConnectionString(connectionString: string): QRPayload {
+  let url: URL;
+
+  try {
+    url = new URL(connectionString);
+  } catch {
+    throw new Error(`Invalid connection string format: ${connectionString}`);
+  }
+
+  // Parse query parameters using our safe decoder
+  const params = parseQueryString(url.search);
+
+  // Support both compact and full parameter formats
+  const sessionId = params.sessionId || params.s; // full or compact
+  let publicKey = params.publicKey || params.key || params.k; // full, universal, or compact
+  let providerId = params.providerId || params.provider || params.p; // full, alt, or compact
+  let relayUrl = params.relay || params.r; // full or compact
+
+  if (!sessionId || !publicKey) {
+    throw new Error('Missing required parameters: sessionId and publicKey');
+  }
+
+  // If we have a compact format public key (params.k), decompress it
+  if (params.k && !params.publicKey && !params.key) {
+    publicKey = decompressPublicKey(params.k);
+  }
+
+  // If we have a compact format provider, expand it
+  if (params.p && !params.providerId && !params.provider) {
+    providerId = PROVIDER_SHORTCODES_REVERSE[params.p] || params.p;
+  }
+
+  // Handle relay URL decompression:
+  // - No relay parameter = production (default)
+  // - Shortcode (d, s) = expand to full environment URL
+  // - Full URL = use as-is
+  if (!relayUrl) {
+    // No relay parameter means production (most common case)
+    relayUrl = 'wss://relay.banana.link/v1';
+  } else if (RELAY_SHORTCODES_REVERSE[relayUrl]) {
+    // Environment shortcode - expand to full URL
+    relayUrl = RELAY_SHORTCODES_REVERSE[relayUrl];
+  }
+  // else: already a full URL, use as-is
+
+  // Ensure public key has AES-GCM prefix for backward compatibility
+  if (publicKey && !publicKey.startsWith('AES-GCM:')) {
+    publicKey = `AES-GCM:${publicKey}`;
+  }
+
+  return {
+    sessionId,
+    publicKey,
+    providerId: providerId || undefined,
+    relayUrl: relayUrl || undefined,
+  };
+}
+
+/**
+ * Validate that a string is a valid connection string
+ */
+export function isValidConnectionString(connectionString: string): boolean {
+  try {
+    decodeConnectionString(connectionString);
+    return true;
+  } catch {
+    return false;
+  }
+}