@bananalink-sdk/protocol 1.2.7

package/src/crypto/utils.ts

@@ -0,0 +1,190 @@
+import type { CryptoProvider, PlatformDetectionResult } from '../types/crypto-provider';
+import { CryptoContext } from './context';
+
+/**
+ * Generate cryptographically secure random bytes
+ *
+ * Uses the global CryptoContext provider (auto-initializes if needed).
+ * For custom provider usage, pass a provider instance.
+ *
+ * @param length - Number of bytes to generate
+ * @param provider - Optional custom provider (uses CryptoContext if not provided)
+ * @returns Cryptographically secure random bytes
+ *
+ * @example
+ * // Default behavior (uses CryptoContext)
+ * const bytes = randomBytes(32);
+ *
+ * @example
+ * // With custom provider
+ * const provider = new NobleCryptoProvider();
+ * const bytes = randomBytes(32, provider);
+ */
+export function randomBytes(length: number, provider?: CryptoProvider): Uint8Array {
+  const activeProvider = provider || CryptoContext.getProvider();
+  const buffer = activeProvider.randomBytes(length);
+  return new Uint8Array(buffer);
+}
+
+/**
+ * Convert ArrayBuffer to base64 string
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Convert base64 string to ArrayBuffer
+ */
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  // Sanitize the base64 string - remove any whitespace and invalid characters
+  const cleanBase64 = base64.replace(/[^A-Za-z0-9+/=]/g, '');
+
+  // Ensure proper padding
+  let paddedBase64 = cleanBase64;
+  while (paddedBase64.length % 4 !== 0) {
+    paddedBase64 += '=';
+  }
+
+  try {
+    const binary = atob(paddedBase64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+  } catch (error) {
+    throw new Error(`Failed to decode base64 string: ${error instanceof Error ? error.message : 'Invalid base64 format'}. Original string: ${base64.substring(0, 50)}...`);
+  }
+}
+
+/**
+ * Convert string to ArrayBuffer
+ */
+export function stringToArrayBuffer(str: string): ArrayBuffer {
+  return new TextEncoder().encode(str).buffer;
+}
+
+/**
+ * Convert ArrayBuffer to string
+ */
+export function arrayBufferToString(buffer: ArrayBuffer): string {
+  return new TextDecoder().decode(buffer);
+}
+
+/**
+ * Generate a cryptographically secure nonce
+ *
+ * @param length - Number of bytes to generate (default: 32)
+ * @param provider - Optional custom provider (uses CryptoContext if not provided)
+ * @returns Hex-encoded string (2 characters per byte)
+ *
+ * @example
+ * generateNonce()    // Returns 64-char hex string (32 bytes)
+ * generateNonce(16)  // Returns 32-char hex string (16 bytes)
+ *
+ * @example
+ * // With custom provider
+ * const provider = new NobleCryptoProvider();
+ * const nonce = generateNonce(32, provider);
+ */
+export function generateNonce(length: number = 32, provider?: CryptoProvider): string {
+  const bytes = randomBytes(length, provider);
+  return Array.from(bytes, (byte: number) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Generate a RFC 4122 version 4 UUID (Universally Unique Identifier)
+ *
+ * Uses cryptographically secure random bytes from the configured CryptoProvider.
+ * This implementation is mobile-safe and works across all platforms (Browser, Node.js, React Native).
+ *
+ * Output format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ * where x is any hexadecimal digit and y is one of 8, 9, a, or b.
+ *
+ * @param provider - Optional custom provider (uses CryptoContext if not provided)
+ * @returns UUID v4 string (36 characters including dashes)
+ *
+ * @example
+ * // Default behavior (uses CryptoContext)
+ * const uuid = generateUUID();
+ * // Example output: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ *
+ * @example
+ * // With custom provider
+ * const provider = new NobleCryptoProvider();
+ * const uuid = generateUUID(provider);
+ */
+export function generateUUID(provider?: CryptoProvider): string {
+  const bytes = randomBytes(16, provider);
+
+  // Set version (4) and variant bits according to RFC 4122
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10
+
+  // Convert to hex string with dashes
+  const hex = Array.from(bytes, (byte: number) => byte.toString(16).padStart(2, '0')).join('');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32)
+  ].join('-');
+}
+
+/**
+ * Detect the current platform/runtime environment
+ *
+ * Provides information about whether code is running in Node.js, browser,
+ * React Native, or other JavaScript environments.
+ *
+ * @returns Platform detection result with environment flags
+ *
+ * @example
+ * const platform = detectPlatform();
+ * if (platform.isNode) {
+ *   console.log('Running in Node.js');
+ * } else if (platform.isBrowser) {
+ *   console.log('Running in browser');
+ * }
+ */
+export function detectPlatform(): PlatformDetectionResult {
+  // Check for Node.js
+  const isNode = typeof process !== 'undefined' &&
+    process.versions != null &&
+    process.versions.node != null;
+
+  // Check for browser
+  const isBrowser = typeof window !== 'undefined' &&
+    typeof document !== 'undefined';
+
+  // Check for React Native
+  const isReactNative = typeof navigator !== 'undefined' &&
+    navigator.product === 'ReactNative';
+
+  // Get platform identifier (Node.js only)
+  let platform: string | undefined;
+  if (isNode && typeof process.platform === 'string') {
+    platform = process.platform;
+  }
+
+  // Get user agent (browser/React Native)
+  let userAgent: string | undefined;
+  if (typeof navigator !== 'undefined' && typeof navigator.userAgent === 'string') {
+    userAgent = navigator.userAgent;
+  }
+
+  return {
+    isNode,
+    isBrowser,
+    isReactNative,
+    platform,
+    userAgent,
+  };
+}

package/src/crypto-export.ts

@@ -0,0 +1,21 @@
+/**
+ * BananaLink Protocol Crypto Export
+ *
+ * Main export point for cryptographic implementations.
+ * Import from '@bananalink-sdk/protocol/crypto' to access these utilities.
+ *
+ * Tree-Shaking Strategy:
+ * - Consumers of @bananalink-sdk/protocol (main export) do NOT bundle crypto
+ * - Only consumers of @bananalink-sdk/protocol/crypto include these implementations
+ * - Provider implementations are tree-shakeable via factory functions
+ *
+ * Bundle Size Impact:
+ * - WebCrypto provider: ~2KB (uses native APIs)
+ * - Noble provider: ~45KB (pure JS fallback)
+ * - QuickCrypto provider: ~3KB (React Native bindings)
+ * - SessionSecurity: ~5KB
+ * - Total (with one provider): ~7-50KB depending on provider
+ */
+
+// Re-export everything from crypto module
+export * from './crypto';

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * BananaLink Protocol Package
+ *
+ * Core TypeScript implementation of the BananaLink protocol for dApp-to-wallet communication.
+ * Provides types, schemas, constants, and utilities for implementing BananaLink clients and wallets.
+ *
+ * @packageDocumentation
+ */
+
+// Core protocol types
+export * from './types/core';
+export * from './types/auth';
+export * from './types/crypto';
+export * from './types/discovery';
+export * from './types/errors';
+export * from './types/providers';
+export * from './types/wallet-messages';
+export * from './types/client-messages';
+export * from './types/relay-messages';
+
+// Note: Zod validation schemas have been moved to '@bananalink-sdk/protocol/schemas'
+// For runtime validation, import from '@bananalink-sdk/protocol/schemas'
+// Type-only definitions remain available from this main export
+
+// Note: SIWE utilities have been moved to '@bananalink-sdk/protocol/siwe'
+// For ERC-4361 message construction/parsing, import from '@bananalink-sdk/protocol/siwe'
+// Export SIWE types for convenience (type-only, no runtime code)
+export type { SIWEMessageOptions } from './utils/siwe';
+
+// Constants and utilities
+export * from './constants';
+export * from './utils';
+
+// Package metadata
+// Note: Version is imported from package.json to ensure consistency
+import packageJson from '../package.json';
+export const VERSION = packageJson.version;
+export const PACKAGE_NAME = "@bananalink-sdk/protocol";

package/src/schemas/auth.ts

@@ -0,0 +1,60 @@
+/**
+ * Authentication validation schemas for BananaLink protocol
+ */
+
+import { z } from 'zod';
+
+// Base validation schemas
+const ethereumAddressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address');
+const iso8601Schema = z.string().datetime({ message: 'Invalid ISO 8601 datetime' });
+const domainSchema = z.string().min(1, 'Domain cannot be empty');
+
+// Import schemas from core
+import { dAppMetadataSchema, sessionConfigSchema } from './core';
+
+// Session state schema
+export const sessionStateSchema = z.enum([
+  'created',
+  'claimed',
+  'authenticated',
+  'active',
+  'disconnected',
+  'closed',
+  'expired',
+  'rejected',
+]);
+
+// Session info schema
+export const sessionInfoSchema = z.object({
+  sessionId: z.string().min(1, 'Session ID cannot be empty'),
+  state: sessionStateSchema,
+  address: ethereumAddressSchema.optional(),
+  dappId: z.string().min(1, 'DApp ID cannot be empty'),
+  dappInfo: dAppMetadataSchema.pick({ name: true, url: true }),
+  sessionConfig: sessionConfigSchema.optional(),
+  createdAt: iso8601Schema,
+  lastActivity: iso8601Schema,
+  expiresAt: iso8601Schema.optional(),
+});
+
+// Origin proof schema
+export const originProofSchema = z.object({
+  domain: domainSchema,
+  timestamp: z.number().int().positive(),
+  signature: z.string().min(1, 'Signature cannot be empty'),
+});
+
+// Session ID validation (UUID v4)
+export const sessionIdSchema = z.string().regex(
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  'Invalid session ID format'
+);
+
+// Validation helper functions
+export const validateSessionInfo = (info: unknown) => sessionInfoSchema.parse(info);
+
+// Safe parsing functions
+export const safeValidateSessionInfo = (info: unknown) => sessionInfoSchema.safeParse(info);
+
+// Note: Types are exported from ./types/auth to avoid conflicts
+// Use z.infer<typeof schemaName> if you need to infer types from schemas

package/src/schemas/client-messages.ts

@@ -0,0 +1,57 @@
+/**
+ * Validation schemas for client message types
+ */
+
+import { z } from 'zod';
+
+// Client session claim schema
+export const clientSessionClaimSchema = z.object({
+  /** Unique nonce for this client session */
+  claimNonce: z.string().min(32, 'Client claim nonce must be at least 32 characters'),
+  /** Claim generation timestamp */
+  timestamp: z.number().int().positive('Timestamp must be a positive integer'),
+});
+
+// Client message payload schemas
+export const clientReconnectPayloadSchema = z.object({
+  type: z.literal('client_reconnect'),
+});
+
+export const closeSessionPayloadSchema = z.object({
+  type: z.literal('close_session'),
+  /** Optional reason for closing the session */
+  reason: z.string().optional(),
+});
+
+// Union of all client message payloads
+export const clientMessagePayloadSchema = z.discriminatedUnion('type', [
+  clientReconnectPayloadSchema,
+  closeSessionPayloadSchema,
+]);
+
+// Client message envelope schema
+export const clientMessageEnvelopeSchema = z.object({
+  /** Session identifier */
+  sessionId: z.string().uuid('Session ID must be a valid UUID'),
+  /** Client session claim */
+  clientSessionClaim: clientSessionClaimSchema,
+  /** Message payload */
+  payload: clientMessagePayloadSchema,
+});
+
+// Validation helper functions
+export const validateClientMessage = (message: unknown) => {
+  return clientMessageEnvelopeSchema.parse(message);
+};
+
+export const safeValidateClientMessage = (message: unknown) => {
+  return clientMessageEnvelopeSchema.safeParse(message);
+};
+
+export const validateClientSessionClaim = (claim: unknown) => {
+  return clientSessionClaimSchema.parse(claim);
+};
+
+export const safeValidateClientSessionClaim = (claim: unknown) => {
+  return clientSessionClaimSchema.safeParse(claim);
+};

package/src/schemas/core.ts

@@ -0,0 +1,144 @@
+/**
+ * Core validation schemas for BananaLink protocol types
+ */
+
+import { z } from 'zod';
+
+// Base validation schemas
+const ethereumAddressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address');
+const hexStringSchema = z.string().regex(/^0x[a-fA-F0-9]*$/, 'Invalid hex string');
+const iso8601Schema = z.string().datetime({ message: 'Invalid ISO 8601 datetime' });
+const urlSchema = z.string().url('Invalid URL');
+const domainSchema = z.string().min(1, 'Domain cannot be empty');
+// Protocol v2.0: 32-byte nonces = 64 hex characters
+const nonceSchema = z
+  .string()
+  .length(64, 'Nonce must be exactly 64 characters (32 bytes hex-encoded)')
+  .regex(/^[a-fA-F0-9]{64}$/, 'Nonce must be a valid 64-character hexadecimal string');
+
+// SIWE base schema
+export const siweFieldsSchema = z.object({
+  scheme: z.string().optional(),
+  domain: domainSchema,
+  address: ethereumAddressSchema,
+  statement: z.string().optional(),
+  uri: urlSchema,
+  version: z.literal('1'),
+  chainId: z.number().int().positive(),
+  nonce: nonceSchema,
+  issuedAt: iso8601Schema,
+  expirationTime: iso8601Schema.optional(),
+  notBefore: iso8601Schema.optional(),
+  requestId: z.string().optional(),
+  resources: z.array(urlSchema).optional(),
+});
+
+// Transaction payload schema
+export const transactionPayloadSchema = z.object({
+  to: ethereumAddressSchema,
+  value: z.string().regex(/^\d+$/, 'Value must be a numeric string').optional(),
+  data: hexStringSchema.optional(),
+  gas: z.string().regex(/^\d+$/, 'Gas must be a numeric string').optional(),
+  gasPrice: z.string().regex(/^\d+$/, 'Gas price must be a numeric string').optional(),
+  maxFeePerGas: z.string().regex(/^\d+$/, 'Max fee per gas must be a numeric string').optional(),
+  maxPriorityFeePerGas: z.string().regex(/^\d+$/, 'Max priority fee per gas must be a numeric string').optional(),
+});
+
+// Sign payload schema
+export const signPayloadSchema = z.object({
+  message: z.string().min(1, 'Message cannot be empty'),
+  encoding: z.enum(['utf8', 'hex']).default('utf8'),
+});
+
+// BananaLink message type schema
+export const messageTypeSchema = z.enum(['auth', 'tx', 'sign']);
+
+// Main BananaLink message schema
+export const bananaLinkMessageSchema = siweFieldsSchema.extend({
+  type: messageTypeSchema,
+  sessionId: z.string().min(1, 'Session ID cannot be empty'),
+  payload: z.union([transactionPayloadSchema, signPayloadSchema]).optional(),
+});
+
+// DApp metadata schema
+export const dAppMetadataSchema = z.object({
+  dappId: z.string().optional(),
+  name: z.string().min(1, 'Name cannot be empty'),
+  description: z.string().optional(),
+  url: urlSchema,
+  icons: z.array(urlSchema).optional(),
+});
+
+// Session configuration schema
+export const sessionConfigSchema = z.object({
+  returnUrl: urlSchema.optional(),
+  sessionName: z.string().optional(),
+  expiresAt: iso8601Schema.optional(),
+  customData: z.record(z.unknown()).optional(),
+});
+
+// BananaLink response schema
+export const bananaLinkResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.unknown().optional(),
+  error: z.string().optional(),
+  requestId: z.string().optional(),
+});
+
+// Security policy schema
+export const securityPolicySchema = z.object({
+  sessionTimeout: z.number().int().positive(),
+  requestTimeout: z.number().int().positive(),
+  maxConcurrentSessions: z.number().int().positive(),
+  requireOriginProof: z.boolean(),
+  allowedDomains: z.array(domainSchema).optional(),
+  blockedDomains: z.array(domainSchema).optional(),
+});
+
+// Session options schema
+export const sessionOptionsSchema = z.object({
+  config: sessionConfigSchema.optional(),
+  securityPolicy: securityPolicySchema.partial().optional(),
+  relayUrl: urlSchema.optional(),
+});
+
+// Session metadata schema (for session creation)
+export const sessionMetadataSchema = z.object({
+  encryptionAlgorithm: z.enum(['AES-GCM', 'plaintext']),
+  sessionId: z.string().min(1, 'Session ID cannot be empty'),
+  publicKey: z.string().optional(),
+  timestamp: iso8601Schema,
+});
+
+// Session creation request schema (Client → API Gateway)
+export const createSessionRequestSchema = z.object({
+  dappId: z.string().uuid('Invalid DApp ID format'),
+  metadata: sessionMetadataSchema,
+  sessionConfig: sessionConfigSchema.optional(),
+});
+
+// Client session claim schema
+export const clientSessionClaimSchema = z.object({
+  /** Unique nonce for client session claim (32 bytes hex-encoded = 64 characters) */
+  claimNonce: z
+    .string()
+    .length(64, 'Claim nonce must be exactly 64 characters (32 bytes hex-encoded)')
+    .regex(/^[0-9a-f]{64}$/, 'Claim nonce must be lowercase hexadecimal'),
+  timestamp: z.number().int().positive(),
+});
+
+// Session creation response schema (API Gateway → Client)
+export const createSessionResponseSchema = z.object({
+  sessionId: z.string().uuid('Invalid session ID format'),
+  clientSessionClaim: clientSessionClaimSchema,
+  ttl: z.number().int().positive(),
+});
+
+// Validation helper functions
+export const validateMessage = (message: unknown) => bananaLinkMessageSchema.parse(message);
+
+// Safe parsing functions
+export const safeValidateMessage = (message: unknown) => bananaLinkMessageSchema.safeParse(message);
+
+// Note: Types are exported from ./types/core to avoid conflicts
+// Use z.infer<typeof schemaName> if you need to infer types from schemas

package/src/schemas/crypto.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for crypto payload validation
+ */
+
+export const KeyExchangeSchema = z.object({
+  algorithm: z.literal('ECDH'),
+  namedCurve: z.literal('P-256'),
+});
+
+export const EncryptionSchema = z.object({
+  algorithm: z.enum(['AES-GCM', 'plaintext']),
+  keyLength: z.literal(256).optional(),
+  tagLength: z.literal(128).optional(),
+});
+
+export const PublicKeyJWKSchema = z.object({
+  kty: z.literal('EC'),
+  crv: z.literal('P-256'),
+  x: z.string().min(1),
+  y: z.string().min(1),
+  use: z.literal('enc'),
+  key_ops: z.tuple([z.literal('deriveKey')]),
+});
+
+export const CryptoParametersSchema = z.object({
+  iv: z.string().optional(),
+  timestamp: z.string().datetime(),
+  sessionId: z.string().uuid(),
+});
+
+export const KeyDerivationSchema = z.object({
+  algorithm: z.literal('HKDF'),
+  hash: z.literal('SHA-256'),
+  info: z.literal('message-exchange-v1'),
+  salt: z.string().min(1),
+});
+
+export const ProductionCryptoPayloadSchema = z.object({
+  version: z.literal('1.0'),
+  keyExchange: KeyExchangeSchema,
+  encryption: EncryptionSchema.extend({
+    algorithm: z.literal('AES-GCM'),
+  }),
+  publicKey: PublicKeyJWKSchema,
+  parameters: CryptoParametersSchema,
+  derivation: KeyDerivationSchema,
+});
+
+export const DevelopmentCryptoPayloadSchema = z.object({
+  version: z.literal('1.0'),
+  encryption: EncryptionSchema.extend({
+    algorithm: z.literal('plaintext'),
+  }),
+  parameters: CryptoParametersSchema,
+});
+
+export const CryptoPayloadSchema = z.union([
+  ProductionCryptoPayloadSchema,
+  DevelopmentCryptoPayloadSchema,
+]);
+
+// Note: Types are exported from ./types/crypto to avoid conflicts
+// Use z.infer<typeof schemaName> if you need to infer types from schemas

package/src/schemas/discovery.ts

@@ -0,0 +1,79 @@
+/**
+ * Discovery validation schemas for BananaLink protocol
+ */
+
+import { z } from 'zod';
+import { FRUITS } from '../constants';
+
+// Base validation schemas
+const urlSchema = z.string().url('Invalid URL');
+
+
+// QR payload schema
+export const qrPayloadSchema = z.object({
+  sessionId: z.string().min(1, 'Session ID cannot be empty'),
+  publicKey: z.string().min(1, 'Public key cannot be empty'),
+  relayUrl: z.string().url().optional(),
+  providerId: z.string().optional(),
+});
+
+// Encrypted payload schema
+export const encryptedPayloadSchema = z.object({
+  iv: z.string().min(1, 'IV cannot be empty'),
+  ciphertext: z.string().min(1, 'Ciphertext cannot be empty'),
+  mac: z.string().min(1, 'MAC cannot be empty'),
+});
+
+// Relay message type schema
+export const relayMessageTypeSchema = z.enum(['pub', 'sub', 'ack', 'error']);
+
+// Relay message schema
+export const relayMessageSchema = z.object({
+  topic: z.string().min(1, 'Topic cannot be empty'),
+  type: relayMessageTypeSchema,
+  payload: encryptedPayloadSchema.optional(),
+  id: z.string().min(1, 'Message ID cannot be empty'),
+});
+
+// Display info schema
+export const displayInfoSchema = z.object({
+  qrCode: z.string().min(1, 'QR code cannot be empty'),
+  frutiLink: z.string().regex(/^[🍌🍎🍊🍇🍓🍑🍒🍉🥝🍍🥭🥥🫐🍈🍋🥑]{8}$/u, 'Invalid FrutiLink format'),
+  deepLink: urlSchema,
+});
+
+// FrutiLink validation
+export const frutiLinkSchema = z.string()
+  .length(8, 'FrutiLink must be exactly 8 characters')
+  .refine(
+    (value) => value.split('').every(char => FRUITS.includes(char as typeof FRUITS[number])),
+    'FrutiLink contains invalid fruits'
+  );
+
+// Public key validation (base64 encoded)
+export const publicKeySchema = z.string()
+  .min(1, 'Public key cannot be empty')
+  .refine(
+    (key) => {
+      try {
+        atob(key);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    'Public key must be valid Base64'
+  );
+
+// Validation helper functions
+export const validateQRPayload = (payload: unknown) => qrPayloadSchema.parse(payload);
+export const validateRelayMessage = (message: unknown) => relayMessageSchema.parse(message);
+export const validateFrutiLink = (frutiLink: unknown) => frutiLinkSchema.parse(frutiLink);
+
+// Safe parsing functions
+export const safeValidateQRPayload = (payload: unknown) => qrPayloadSchema.safeParse(payload);
+export const safeValidateRelayMessage = (message: unknown) => relayMessageSchema.safeParse(message);
+export const safeValidateFrutiLink = (frutiLink: unknown) => frutiLinkSchema.safeParse(frutiLink);
+
+// Note: Types are exported from ./types/discovery to avoid conflicts
+// Use z.infer<typeof schemaName> if you need to infer types from schemas