@bananalink-sdk/protocol 1.2.7

package/src/schemas/index.ts

@@ -0,0 +1,239 @@
+/**
+ * Zod validation schemas for BananaLink protocol types
+ * Provides runtime type validation for all protocol messages
+ */
+
+import { z } from 'zod';
+import { FRUITS, NETWORK_CONFIG } from '../constants';
+
+// 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 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(),
+});
+
+// DApp metadata schema
+export const dAppMetadataSchema = z.object({
+  returnUrl: urlSchema.optional(),
+});
+
+// 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'),
+  providerId: z.string().optional(),
+  relayUrl: z.string().url().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'),
+});
+
+// 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(),
+});
+
+// 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 state schema (Protocol v2.0)
+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(),
+  metadata: dAppMetadataSchema,
+  createdAt: iso8601Schema,
+  lastActivity: iso8601Schema,
+  expiresAt: iso8601Schema.optional(),
+});
+
+// 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,
+});
+
+// Error code schema (Protocol v2.0+)
+export const errorCodeSchema = z.enum([
+  // Session errors
+  'SESSION_EXPIRED',
+  'SESSION_NOT_FOUND',
+  'SESSION_ALREADY_CLAIMED',
+  'INVALID_SESSION_CLAIM',
+  'INVALID_CLIENT_CLAIM',
+  'SESSION_TOKEN_EXPIRED',
+  'SESSION_CLOSED',
+  // Encryption errors
+  'ENCRYPTION_FAILED',
+  'DECRYPTION_FAILED',
+  'INVALID_SIGNATURE',
+  // Network errors
+  'NETWORK_ERROR',
+  'RELAY_ERROR',
+  'MESSAGE_QUEUE_FULL',
+  'RATE_LIMIT_EXCEEDED',
+  'ORIGIN_MISMATCH',
+  // Request lifecycle errors (v2.1+)
+  'REQUEST_PENDING',
+  'REQUEST_NOT_FOUND',
+  'REQUEST_EXPIRED',
+  'REQUEST_INVALID',
+  'REQUEST_TIMEOUT',
+  // Operation-specific errors (v2.1+)
+  'SIGNING_FAILED',
+  'SIGNING_REJECTED',
+  'TRANSACTION_INVALID',
+  'CHAIN_MISMATCH',
+]);
+
+// BananaLink error schema
+export const bananaLinkErrorSchema = z.object({
+  code: errorCodeSchema,
+  message: z.string().min(1, 'Error message cannot be empty'),
+  details: z.unknown().optional(),
+});
+
+// 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'
+  );
+
+// Supported chain ID validation
+export const supportedChainIdSchema = z.number()
+  .int()
+  .refine(
+    (chainId) => NETWORK_CONFIG.SUPPORTED_CHAINS.includes(chainId as typeof NETWORK_CONFIG.SUPPORTED_CHAINS[number]),
+    'Unsupported chain ID'
+  );
+
+// Base64 string validation
+export const base64Schema = z.string().regex(
+  /^[A-Za-z0-9+/]*={0,2}$/,
+  'Invalid Base64 string'
+);
+
+// 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'
+);
+
+// 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 (Protocol v2.0)
+export const validateQRPayload = (payload: unknown) => qrPayloadSchema.parse(payload);
+export const validateRelayMessage = (message: unknown) => relayMessageSchema.parse(message);
+export const validateSessionInfo = (info: unknown) => sessionInfoSchema.parse(info);
+export const validateFrutiLink = (frutiLink: unknown) => frutiLinkSchema.parse(frutiLink);
+
+// Safe parsing functions (returns { success: boolean, data?: T, error?: ZodError })
+export const safeValidateQRPayload = (payload: unknown) => qrPayloadSchema.safeParse(payload);
+export const safeValidateRelayMessage = (message: unknown) => relayMessageSchema.safeParse(message);
+export const safeValidateSessionInfo = (info: unknown) => sessionInfoSchema.safeParse(info);
+export const safeValidateFrutiLink = (frutiLink: unknown) => frutiLinkSchema.safeParse(frutiLink);
+
+// Type inference from schemas (Protocol v2.0)
+export type SIWEFields = z.infer<typeof siweFieldsSchema>;
+export type DAppMetadata = z.infer<typeof dAppMetadataSchema>;
+export type QRPayload = z.infer<typeof qrPayloadSchema>;
+export type EncryptedPayload = z.infer<typeof encryptedPayloadSchema>;
+export type RelayMessage = z.infer<typeof relayMessageSchema>;
+export type SecurityPolicy = z.infer<typeof securityPolicySchema>;
+export type SessionInfo = z.infer<typeof sessionInfoSchema>;
+export type DisplayInfo = z.infer<typeof displayInfoSchema>;
+
+// Re-export core schemas (Protocol v2.0)
+export {
+  dAppMetadataSchema as coreDAppMetadataSchema,
+  sessionConfigSchema,
+  sessionOptionsSchema,
+  sessionMetadataSchema,
+  createSessionRequestSchema,
+  createSessionResponseSchema,
+  clientSessionClaimSchema,
+  securityPolicySchema as coreSecurityPolicySchema,
+} from './core';
+
+// Re-export v2.0 wallet message schemas
+export * from './wallet-messages';
+
+// Re-export v2.0 client message schemas
+export * from './client-messages';
+
+// Re-export v2.0 relay message schemas
+export * from './relay-messages';

package/src/schemas/relay-messages.ts

@@ -0,0 +1,45 @@
+/**
+ * Validation schemas for relay notification message types
+ */
+
+import { z } from 'zod';
+
+// Session closed acknowledgment schema
+export const sessionClosedAckSchema = z.object({
+  type: z.literal('session_closed_ack'),
+  timestamp: z.number().int().positive(),
+});
+
+// Session closed notification schema
+export const sessionClosedNotificationSchema = z.object({
+  type: z.literal('session_closed_notification'),
+  /** Which party closed the session */
+  closedBy: z.enum(['client', 'wallet']),
+  /** Optional reason for closure */
+  reason: z.string().optional(),
+  timestamp: z.number().int().positive(),
+});
+
+// Reconnected message schema
+export const reconnectedMessageSchema = z.object({
+  type: z.literal('reconnected'),
+  /** Number of messages that were queued during disconnection */
+  queuedMessages: z.number().int().nonnegative(),
+  timestamp: z.number().int().positive(),
+});
+
+// Union of all relay notification messages
+export const relayNotificationMessageSchema = z.discriminatedUnion('type', [
+  sessionClosedAckSchema,
+  sessionClosedNotificationSchema,
+  reconnectedMessageSchema,
+]);
+
+// Validation helper functions
+export const validateRelayNotificationMessage = (message: unknown) => {
+  return relayNotificationMessageSchema.parse(message);
+};
+
+export const safeValidateRelayNotificationMessage = (message: unknown) => {
+  return relayNotificationMessageSchema.safeParse(message);
+};

package/src/schemas/wallet-messages.ts

@@ -0,0 +1,177 @@
+/**
+ * Validation schemas for wallet message types
+ */
+
+import { z } from 'zod';
+import { dAppMetadataSchema, sessionConfigSchema } from './core';
+import { encryptedPayloadSchema } from './discovery';
+
+// Re-export encryptedPayloadSchema for convenience
+export { encryptedPayloadSchema };
+
+// Wallet session claim schema
+export const walletSessionClaimSchema = z.object({
+  /** Unique nonce for this session claim (32 bytes hex-encoded = 64 characters) */
+  sessionNonce: z
+    .string()
+    .length(64, 'Session nonce must be exactly 64 characters (32 bytes hex-encoded)')
+    .regex(/^[0-9a-f]{64}$/, 'Session nonce must be lowercase hexadecimal'),
+  /** Claim timestamp */
+  timestamp: z.number().int().positive('Timestamp must be a positive integer'),
+});
+
+// Wallet message payload schemas
+export const claimSessionPayloadSchema = z.object({
+  type: z.literal('claim_session'),
+  /** Wallet's public key for ECDH key exchange - format: "algorithm:key_data" (e.g., "AES-GCM:base64..." or "cleartext:none") */
+  walletPublicKey: z
+    .string()
+    .min(1, 'Wallet public key cannot be empty')
+    .regex(/^(AES-GCM:|cleartext:)/, 'Wallet public key must start with "AES-GCM:" or "cleartext:"'),
+});
+
+export const prefetchMetadataPayloadSchema = z.object({
+  type: z.literal('prefetch_metadata'),
+});
+
+export const connectionRejectedPayloadSchema = z.object({
+  type: z.literal('connection_rejected'),
+  encrypted: encryptedPayloadSchema,
+});
+
+export const authenticateConnectionPayloadSchema = z.object({
+  type: z.literal('authenticate_connection'),
+  encrypted: encryptedPayloadSchema,
+});
+
+export const walletReconnectPayloadSchema = z.object({
+  type: z.literal('wallet_reconnect'),
+});
+
+// Union of all wallet message payloads
+export const walletMessagePayloadSchema = z.discriminatedUnion('type', [
+  claimSessionPayloadSchema,
+  prefetchMetadataPayloadSchema,
+  connectionRejectedPayloadSchema,
+  authenticateConnectionPayloadSchema,
+  walletReconnectPayloadSchema,
+]);
+
+// Wallet message envelope schema
+export const walletMessageEnvelopeSchema = z.object({
+  /** Session identifier */
+  sessionId: z.string().uuid('Session ID must be a valid UUID'),
+  /** Wallet session claim credential */
+  walletSessionClaim: walletSessionClaimSchema,
+  /** Message payload */
+  payload: walletMessagePayloadSchema,
+});
+
+// Decrypted data schemas
+export const rejectionDataSchema = z.object({
+  reason: z.string().optional(),
+  timestamp: z.number().int().positive(),
+});
+
+export const walletMetadataSchema = z.object({
+  /** Wallet name */
+  name: z.string().min(1, 'Wallet name cannot be empty'),
+  /** Wallet version */
+  version: z.string().optional(),
+  /** Wallet icon URL */
+  icon: z.string().url('Invalid icon URL').optional(),
+  /** Wallet description */
+  description: z.string().optional(),
+  /** Wallet website URL */
+  url: z.string().url('Invalid wallet URL').optional(),
+  /** Wallet provider type */
+  provider: z.string().optional(),
+});
+
+export const authenticationDataSchema = z.object({
+  /** Wallet address */
+  address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address'),
+  /** Signature of the SIWE message */
+  signature: z.string().regex(/^0x[a-fA-F0-9]+$/, 'Invalid signature format'),
+  /** Full SIWE message that was signed */
+  message: z.string().min(1, 'Message cannot be empty'),
+  /** Chain ID (EIP-155) */
+  chainId: z.number().int().positive('Chain ID must be a positive integer'),
+  /** Network identifier */
+  network: z.string().optional(),
+  /** Signing algorithm */
+  signingAlgo: z.string().optional(),
+  /** Optional wallet metadata */
+  walletMetadata: walletMetadataSchema.optional(),
+});
+
+// Relay-to-dApp message schemas
+export const walletHandshakeMessageSchema = z.object({
+  type: z.literal('wallet_handshake'),
+  status: z.literal('reviewing'),
+  /** Wallet's public key in format "algorithm:base64_public_key" */
+  walletPublicKey: z.string(),
+  timestamp: z.number().int().positive(),
+});
+
+export const connectionRejectedMessageSchema = z.object({
+  type: z.literal('connection_rejected'),
+  encrypted: encryptedPayloadSchema,
+});
+
+export const connectionAuthenticatedMessageSchema = z.object({
+  type: z.literal('connection_authenticated'),
+  encrypted: encryptedPayloadSchema,
+});
+
+// Union of relay-to-dApp messages
+export const relayToDAppMessageSchema = z.discriminatedUnion('type', [
+  walletHandshakeMessageSchema,
+  connectionRejectedMessageSchema,
+  connectionAuthenticatedMessageSchema,
+]);
+
+// Prefetch metadata response schema
+export const prefetchMetadataResponseSchema = z.object({
+  dappMetadata: dAppMetadataSchema,
+  sessionConfig: sessionConfigSchema.optional(),
+});
+
+// Validation helper functions
+export const validateWalletMessage = (message: unknown) => {
+  return walletMessageEnvelopeSchema.parse(message);
+};
+
+export const safeValidateWalletMessage = (message: unknown) => {
+  return walletMessageEnvelopeSchema.safeParse(message);
+};
+
+export const validateRelayToDAppMessage = (message: unknown) => {
+  return relayToDAppMessageSchema.parse(message);
+};
+
+export const safeValidateRelayToDAppMessage = (message: unknown) => {
+  return relayToDAppMessageSchema.safeParse(message);
+};
+
+export const validateWalletSessionClaim = (claim: unknown) => {
+  return walletSessionClaimSchema.parse(claim);
+};
+
+export const safeValidateWalletSessionClaim = (claim: unknown) => {
+  return walletSessionClaimSchema.safeParse(claim);
+};
+
+/**
+ * Validate timestamp for replay attack prevention
+ * @param timestamp - Timestamp to validate
+ * @param maxAge - Maximum age in milliseconds (default: 5 minutes)
+ */
+export function validateTimestamp(timestamp: number, maxAge: number = 5 * 60 * 1000): boolean {
+  const now = Date.now();
+  const age = Math.abs(now - timestamp);
+  return age <= maxAge;
+}
+
+// NOTE: Nonce generation moved to @bananalink-sdk/crypto package to avoid circular dependencies
+// SDKs should use crypto.generateSessionNonce() before validating session claims

package/src/schemas-export.ts

@@ -0,0 +1,23 @@
+/**
+ * Zod validation schemas for BananaLink protocol
+ *
+ * This module exports all runtime validation schemas for the BananaLink protocol.
+ * Import from '@bananalink-sdk/protocol/schemas' when you need runtime validation.
+ *
+ * For TypeScript type definitions only, import from '@bananalink-sdk/protocol' instead.
+ *
+ * @example
+ * ```typescript
+ * // Runtime validation
+ * import { sessionStateSchema, validateMessage } from '@bananalink-sdk/protocol/schemas';
+ *
+ * // Type-only imports
+ * import type { SessionState, BananaLinkMessage } from '@bananalink-sdk/protocol';
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Re-export all schemas via the main schemas index
+// (which already aggregates all schema modules)
+export * from './schemas';

package/src/siwe-export.ts

@@ -0,0 +1,27 @@
+/**
+ * SIWE (Sign-In with Ethereum) utilities for BananaLink protocol
+ *
+ * This module exports ERC-4361 compliant message construction and validation utilities.
+ * Import from '@bananalink-sdk/protocol/siwe' when you need SIWE message handling.
+ *
+ * Most SDKs and applications won't need this module unless implementing custom
+ * authentication flows or wallet integration at the protocol level.
+ *
+ * @example
+ * ```typescript
+ * // SIWE message construction and validation
+ * import {
+ *   constructSIWEMessage,
+ *   parseSIWEMessage,
+ *   validateSIWEMessage
+ * } from '@bananalink-sdk/protocol/siwe';
+ *
+ * // Type-only imports (available from main export)
+ * import type { SIWEFields, SIWEMessageOptions } from '@bananalink-sdk/protocol';
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Re-export all SIWE utilities
+export * from './utils/siwe';

package/src/testing.ts

@@ -0,0 +1,71 @@
+/**
+ * Testing utilities for @bananalink-sdk/protocol
+ *
+ * This module provides test utilities and mock implementations
+ * for testing BananaLink protocol integrations.
+ *
+ * @packageDocumentation
+ */
+
+import type { WalletSessionClaim } from './types/wallet-messages';
+import type { ClientSessionClaim } from './types/client-messages';
+
+// Re-export storage interfaces
+export type { WalletSessionClaimStorage } from './utils/wallet-session-claim';
+export type { ClientSessionClaimStorage } from './utils/client-session-claim';
+
+/**
+ * In-memory wallet session claim storage (for testing/development)
+ *
+ * WARNING: Do not use in production - claims should persist across app restarts
+ */
+export class InMemoryWalletSessionClaimStorage {
+  private claims: Map<string, WalletSessionClaim> = new Map();
+
+  store(sessionId: string, claim: WalletSessionClaim): Promise<void> {
+    this.claims.set(sessionId, claim);
+    return Promise.resolve();
+  }
+
+  retrieve(sessionId: string): Promise<WalletSessionClaim | null> {
+    return Promise.resolve(this.claims.get(sessionId) || null);
+  }
+
+  remove(sessionId: string): Promise<void> {
+    this.claims.delete(sessionId);
+    return Promise.resolve();
+  }
+
+  clear(): Promise<void> {
+    this.claims.clear();
+    return Promise.resolve();
+  }
+}
+
+/**
+ * In-memory client session claim storage (for testing/development)
+ *
+ * WARNING: Do not use in production - claims should persist across page reloads
+ */
+export class InMemoryClientSessionClaimStorage {
+  private claims: Map<string, ClientSessionClaim> = new Map();
+
+  store(sessionId: string, claim: ClientSessionClaim): Promise<void> {
+    this.claims.set(sessionId, claim);
+    return Promise.resolve();
+  }
+
+  retrieve(sessionId: string): Promise<ClientSessionClaim | null> {
+    return Promise.resolve(this.claims.get(sessionId) || null);
+  }
+
+  remove(sessionId: string): Promise<void> {
+    this.claims.delete(sessionId);
+    return Promise.resolve();
+  }
+
+  clear(): Promise<void> {
+    this.claims.clear();
+    return Promise.resolve();
+  }
+}

package/src/types/auth.ts

@@ -0,0 +1,60 @@
+/**
+ * Authentication types for the BananaLink protocol
+ */
+
+// Import to ensure global type declarations are available
+import './index';
+
+// Session state
+export type SessionState =
+  | 'created'          // Session created by API Gateway
+  | 'claimed'          // Wallet claimed session
+  | 'authenticated'    // Wallet authenticated successfully
+  | 'active'           // Both parties connected and communicating
+  | 'disconnected'     // One or both parties temporarily disconnected
+  | 'closed'           // Gracefully terminated via close_session
+  | 'expired'          // TTL exceeded without activity
+  | 'rejected';        // Wallet explicitly rejected connection
+
+// Session information
+export interface SessionInfo {
+  /** Session identifier */
+  sessionId: string;
+  /** Current state */
+  state: SessionState;
+  /** Connected address (if any) */
+  address?: string;
+  /** DApp identifier */
+  dappId: string;
+  /** Essential dApp info */
+  dappInfo: Pick<DAppMetadata, 'name' | 'url'>;
+  /** Session-specific configuration */
+  sessionConfig?: SessionConfig;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last activity timestamp */
+  lastActivity: string;
+  /** Expiration timestamp */
+  expiresAt?: string;
+}
+
+// Session security configuration
+export interface SessionSecurity {
+  /** Shared secret for encryption */
+  sharedSecret: CryptoKey;
+  /** Session identifier */
+  sessionId: string;
+}
+
+// Origin proof for domain verification
+export interface OriginProof {
+  /** Domain asserting ownership */
+  domain: string;
+  /** Timestamp of the proof */
+  timestamp: number;
+  /** Signature proving domain ownership */
+  signature: string;
+}
+
+// Import types from core
+import type { DAppMetadata, SessionConfig } from './core';