@antseed/node 0.1.0

package/src/p2p/nat-traversal.ts

@@ -0,0 +1,169 @@
+import NatAPI from "@silentbot1/nat-api";
+import { debugLog, debugWarn } from "../utils/debug.js";
+
+export interface NatMapping {
+  /** The internal port that was mapped. */
+  internalPort: number;
+  /** The external port on the router (usually same as internal). */
+  externalPort: number;
+  /** The external/public IP address. */
+  externalIp: string;
+  /** Protocol that was mapped. */
+  protocol: "TCP" | "UDP";
+}
+
+export interface NatTraversalResult {
+  /** Whether UPnP/NAT-PMP mapping succeeded. */
+  success: boolean;
+  /** External IP if discovered. */
+  externalIp: string | null;
+  /** Successfully created mappings. */
+  mappings: NatMapping[];
+}
+
+/**
+ * Automatic NAT traversal via UPnP and NAT-PMP.
+ *
+ * Requests port forwarding from the router so that inbound connections
+ * from the internet can reach the seller's signaling port. This is
+ * transparent to the caller — just call `mapPorts()` after binding
+ * and `cleanup()` on shutdown.
+ */
+export class NatTraversal {
+  private _nat: NatAPI | null = null;
+  private _mappings: NatMapping[] = [];
+  private _externalIp: string | null = null;
+  private _destroyed = false;
+
+  /**
+   * Attempt to map the given ports via UPnP/NAT-PMP.
+   *
+   * @param ports - Array of { port, protocol } to map.
+   * @param timeoutMs - How long to wait before giving up (default 10s).
+   * @returns Result indicating success and discovered external IP.
+   */
+  async mapPorts(
+    ports: Array<{ port: number; protocol: "TCP" | "UDP" }>,
+    timeoutMs = 10_000,
+  ): Promise<NatTraversalResult> {
+    this._nat = new NatAPI({
+      enablePMP: true,
+      enableUPNP: true,
+      description: "Antseed P2P",
+      ttl: 7200,
+    });
+
+    const result: NatTraversalResult = {
+      success: false,
+      externalIp: null,
+      mappings: [],
+    };
+
+    // Race against timeout
+    try {
+      await Promise.race([
+        this._doMapping(ports, result),
+        rejectAfter(timeoutMs, "NAT traversal timed out"),
+      ]);
+    } catch (err) {
+      // Timeout or error — return partial result
+      const msg = err instanceof Error ? err.message : String(err);
+      debugWarn(`[NAT] ${msg}`);
+    }
+
+    this._mappings = result.mappings;
+    this._externalIp = result.externalIp;
+    result.success = result.mappings.length > 0;
+
+    return result;
+  }
+
+  private async _doMapping(
+    ports: Array<{ port: number; protocol: "TCP" | "UDP" }>,
+    result: NatTraversalResult,
+  ): Promise<void> {
+    if (!this._nat) return;
+
+    // Try to get external IP first
+    try {
+      const ip = await this._nat.externalIp();
+      if (ip) {
+        result.externalIp = ip;
+        debugLog(`[NAT] External IP: ${ip}`);
+      }
+    } catch {
+      debugWarn("[NAT] Could not determine external IP");
+    }
+
+    // Map each port
+    for (const { port, protocol } of ports) {
+      try {
+        const mapped = await this._nat.map({
+          publicPort: port,
+          privatePort: port,
+          protocol,
+          description: `Antseed ${protocol}`,
+        });
+
+        if (mapped) {
+          const mapping: NatMapping = {
+            internalPort: port,
+            externalPort: port,
+            externalIp: result.externalIp ?? "",
+            protocol,
+          };
+          result.mappings.push(mapping);
+          debugLog(`[NAT] Mapped ${protocol} port ${port}`);
+        } else {
+          debugWarn(`[NAT] Failed to map ${protocol} port ${port}`);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        debugWarn(`[NAT] Error mapping ${protocol} port ${port}: ${msg}`);
+      }
+    }
+  }
+
+  /** The external IP discovered during mapping, if any. */
+  get externalIp(): string | null {
+    return this._externalIp;
+  }
+
+  /** All active port mappings. */
+  get mappings(): readonly NatMapping[] {
+    return this._mappings;
+  }
+
+  /** Remove all port mappings and clean up. */
+  async cleanup(): Promise<void> {
+    if (this._destroyed || !this._nat) return;
+    this._destroyed = true;
+
+    for (const m of this._mappings) {
+      try {
+        await this._nat.unmap({
+          publicPort: m.externalPort,
+          privatePort: m.internalPort,
+          protocol: m.protocol,
+        });
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+
+    try {
+      await this._nat.destroy();
+    } catch {
+      // Best-effort cleanup
+    }
+
+    this._mappings = [];
+    this._nat = null;
+  }
+}
+
+function rejectAfter(ms: number, message: string): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => reject(new Error(message)), ms);
+  });
+}

package/src/p2p/payment-codec.ts

@@ -0,0 +1,165 @@
+import type {
+  SessionLockAuthPayload,
+  SessionLockConfirmPayload,
+  SessionLockRejectPayload,
+  SellerReceiptPayload,
+  BuyerAckPayload,
+  SessionEndPayload,
+  TopUpRequestPayload,
+  TopUpAuthPayload,
+  DisputeNotifyPayload,
+} from '../types/protocol.js';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+// --- Validation helpers ---
+
+function parseJson(data: Uint8Array): Record<string, unknown> {
+  const raw: unknown = JSON.parse(decoder.decode(data));
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error('Expected JSON object');
+  }
+  return raw as Record<string, unknown>;
+}
+
+function requireString(obj: Record<string, unknown>, field: string): string {
+  const val = obj[field];
+  if (typeof val !== 'string' || val.length === 0) {
+    throw new Error(`Missing or invalid string field: ${field}`);
+  }
+  return val;
+}
+
+function requireNumber(obj: Record<string, unknown>, field: string): number {
+  const val = obj[field];
+  if (typeof val !== 'number' || !Number.isFinite(val)) {
+    throw new Error(`Missing or invalid number field: ${field}`);
+  }
+  return val;
+}
+
+// --- Encoders ---
+
+export function encodeSessionLockAuth(payload: SessionLockAuthPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeSessionLockConfirm(payload: SessionLockConfirmPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeSessionLockReject(payload: SessionLockRejectPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeSellerReceipt(payload: SellerReceiptPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeBuyerAck(payload: BuyerAckPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeSessionEnd(payload: SessionEndPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeTopUpRequest(payload: TopUpRequestPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeTopUpAuth(payload: TopUpAuthPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+export function encodeDisputeNotify(payload: DisputeNotifyPayload): Uint8Array {
+  return encoder.encode(JSON.stringify(payload));
+}
+
+// --- Decoders (with runtime validation) ---
+
+export function decodeSessionLockAuth(data: Uint8Array): SessionLockAuthPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    lockedAmount: requireString(obj, 'lockedAmount'),
+    buyerSig: requireString(obj, 'buyerSig'),
+  };
+}
+
+export function decodeSessionLockConfirm(data: Uint8Array): SessionLockConfirmPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    txSignature: requireString(obj, 'txSignature'),
+  };
+}
+
+export function decodeSessionLockReject(data: Uint8Array): SessionLockRejectPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    reason: requireString(obj, 'reason'),
+  };
+}
+
+export function decodeSellerReceipt(data: Uint8Array): SellerReceiptPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    runningTotal: requireString(obj, 'runningTotal'),
+    requestCount: requireNumber(obj, 'requestCount'),
+    responseHash: requireString(obj, 'responseHash'),
+    sellerSig: requireString(obj, 'sellerSig'),
+  };
+}
+
+export function decodeBuyerAck(data: Uint8Array): BuyerAckPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    runningTotal: requireString(obj, 'runningTotal'),
+    requestCount: requireNumber(obj, 'requestCount'),
+    buyerSig: requireString(obj, 'buyerSig'),
+  };
+}
+
+export function decodeSessionEnd(data: Uint8Array): SessionEndPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    runningTotal: requireString(obj, 'runningTotal'),
+    requestCount: requireNumber(obj, 'requestCount'),
+    score: requireNumber(obj, 'score'),
+    buyerSig: requireString(obj, 'buyerSig'),
+  };
+}
+
+export function decodeTopUpRequest(data: Uint8Array): TopUpRequestPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    additionalAmount: requireString(obj, 'additionalAmount'),
+    currentRunningTotal: requireString(obj, 'currentRunningTotal'),
+    currentLockedAmount: requireString(obj, 'currentLockedAmount'),
+  };
+}
+
+export function decodeTopUpAuth(data: Uint8Array): TopUpAuthPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    additionalAmount: requireString(obj, 'additionalAmount'),
+    buyerSig: requireString(obj, 'buyerSig'),
+  };
+}
+
+export function decodeDisputeNotify(data: Uint8Array): DisputeNotifyPayload {
+  const obj = parseJson(data);
+  return {
+    sessionId: requireString(obj, 'sessionId'),
+    reason: requireString(obj, 'reason'),
+    txSignature: requireString(obj, 'txSignature'),
+  };
+}

package/src/p2p/payment-mux.ts

@@ -0,0 +1,153 @@
+import type { PeerConnection } from './connection-manager.js';
+import { MessageType } from '../types/protocol.js';
+import type {
+  SessionLockAuthPayload,
+  SessionLockConfirmPayload,
+  SessionLockRejectPayload,
+  SellerReceiptPayload,
+  BuyerAckPayload,
+  SessionEndPayload,
+  TopUpRequestPayload,
+  TopUpAuthPayload,
+  DisputeNotifyPayload,
+} from '../types/protocol.js';
+import { encodeFrame } from './message-protocol.js';
+import type { FramedMessage } from '../types/protocol.js';
+import * as codec from './payment-codec.js';
+
+export type PaymentMessageHandler<T> = (payload: T) => void | Promise<void>;
+
+/**
+ * Multiplexes bilateral payment messages over a PeerConnection.
+ * Register handlers for each message type, then call handleFrame()
+ * when a payment-range frame arrives.
+ */
+export class PaymentMux {
+  private _connection: PeerConnection;
+  private _messageIdCounter = 0;
+
+  // Handler registrations
+  private _onSessionLockAuth?: PaymentMessageHandler<SessionLockAuthPayload>;
+  private _onSessionLockConfirm?: PaymentMessageHandler<SessionLockConfirmPayload>;
+  private _onSessionLockReject?: PaymentMessageHandler<SessionLockRejectPayload>;
+  private _onSellerReceipt?: PaymentMessageHandler<SellerReceiptPayload>;
+  private _onBuyerAck?: PaymentMessageHandler<BuyerAckPayload>;
+  private _onSessionEnd?: PaymentMessageHandler<SessionEndPayload>;
+  private _onTopUpRequest?: PaymentMessageHandler<TopUpRequestPayload>;
+  private _onTopUpAuth?: PaymentMessageHandler<TopUpAuthPayload>;
+  private _onDisputeNotify?: PaymentMessageHandler<DisputeNotifyPayload>;
+
+  constructor(connection: PeerConnection) {
+    this._connection = connection;
+  }
+
+  // --- Handler registration ---
+  onSessionLockAuth(handler: PaymentMessageHandler<SessionLockAuthPayload>): void {
+    this._onSessionLockAuth = handler;
+  }
+  onSessionLockConfirm(handler: PaymentMessageHandler<SessionLockConfirmPayload>): void {
+    this._onSessionLockConfirm = handler;
+  }
+  onSessionLockReject(handler: PaymentMessageHandler<SessionLockRejectPayload>): void {
+    this._onSessionLockReject = handler;
+  }
+  onSellerReceipt(handler: PaymentMessageHandler<SellerReceiptPayload>): void {
+    this._onSellerReceipt = handler;
+  }
+  onBuyerAck(handler: PaymentMessageHandler<BuyerAckPayload>): void {
+    this._onBuyerAck = handler;
+  }
+  onSessionEnd(handler: PaymentMessageHandler<SessionEndPayload>): void {
+    this._onSessionEnd = handler;
+  }
+  onTopUpRequest(handler: PaymentMessageHandler<TopUpRequestPayload>): void {
+    this._onTopUpRequest = handler;
+  }
+  onTopUpAuth(handler: PaymentMessageHandler<TopUpAuthPayload>): void {
+    this._onTopUpAuth = handler;
+  }
+  onDisputeNotify(handler: PaymentMessageHandler<DisputeNotifyPayload>): void {
+    this._onDisputeNotify = handler;
+  }
+
+  // --- Sending ---
+  sendSessionLockAuth(payload: SessionLockAuthPayload): void {
+    this._send(MessageType.SessionLockAuth, codec.encodeSessionLockAuth(payload));
+  }
+  sendSessionLockConfirm(payload: SessionLockConfirmPayload): void {
+    this._send(MessageType.SessionLockConfirm, codec.encodeSessionLockConfirm(payload));
+  }
+  sendSessionLockReject(payload: SessionLockRejectPayload): void {
+    this._send(MessageType.SessionLockReject, codec.encodeSessionLockReject(payload));
+  }
+  sendSellerReceipt(payload: SellerReceiptPayload): void {
+    this._send(MessageType.SellerReceipt, codec.encodeSellerReceipt(payload));
+  }
+  sendBuyerAck(payload: BuyerAckPayload): void {
+    this._send(MessageType.BuyerAck, codec.encodeBuyerAck(payload));
+  }
+  sendSessionEnd(payload: SessionEndPayload): void {
+    this._send(MessageType.SessionEnd, codec.encodeSessionEnd(payload));
+  }
+  sendTopUpRequest(payload: TopUpRequestPayload): void {
+    this._send(MessageType.TopUpRequest, codec.encodeTopUpRequest(payload));
+  }
+  sendTopUpAuth(payload: TopUpAuthPayload): void {
+    this._send(MessageType.TopUpAuth, codec.encodeTopUpAuth(payload));
+  }
+  sendDisputeNotify(payload: DisputeNotifyPayload): void {
+    this._send(MessageType.DisputeNotify, codec.encodeDisputeNotify(payload));
+  }
+
+  // --- Receiving ---
+  /**
+   * Returns true if this frame is a payment message and was handled.
+   */
+  async handleFrame(frame: FramedMessage): Promise<boolean> {
+    switch (frame.type) {
+      case MessageType.SessionLockAuth:
+        await this._onSessionLockAuth?.(codec.decodeSessionLockAuth(frame.payload));
+        return true;
+      case MessageType.SessionLockConfirm:
+        await this._onSessionLockConfirm?.(codec.decodeSessionLockConfirm(frame.payload));
+        return true;
+      case MessageType.SessionLockReject:
+        await this._onSessionLockReject?.(codec.decodeSessionLockReject(frame.payload));
+        return true;
+      case MessageType.SellerReceipt:
+        await this._onSellerReceipt?.(codec.decodeSellerReceipt(frame.payload));
+        return true;
+      case MessageType.BuyerAck:
+        await this._onBuyerAck?.(codec.decodeBuyerAck(frame.payload));
+        return true;
+      case MessageType.SessionEnd:
+        await this._onSessionEnd?.(codec.decodeSessionEnd(frame.payload));
+        return true;
+      case MessageType.TopUpRequest:
+        await this._onTopUpRequest?.(codec.decodeTopUpRequest(frame.payload));
+        return true;
+      case MessageType.TopUpAuth:
+        await this._onTopUpAuth?.(codec.decodeTopUpAuth(frame.payload));
+        return true;
+      case MessageType.DisputeNotify:
+        await this._onDisputeNotify?.(codec.decodeDisputeNotify(frame.payload));
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  /** Check if a message type is in the payment range (0x50-0x5F). */
+  static isPaymentMessage(type: number): boolean {
+    return type >= 0x50 && type <= 0x5f;
+  }
+
+  private _send(type: MessageType, payload: Uint8Array): void {
+    const frame = encodeFrame({
+      type,
+      messageId: this._messageIdCounter++ & 0xffffffff,
+      payload,
+    });
+    this._connection.send(frame);
+  }
+}

package/src/p2p/reconnect.ts

@@ -0,0 +1,117 @@
+/** Configuration for the reconnection strategy. */
+export interface ReconnectConfig {
+  /** Base delay in milliseconds before the first reconnect attempt. */
+  baseDelayMs?: number;
+  /** Maximum delay in milliseconds between reconnect attempts. */
+  maxDelayMs?: number;
+  /** Maximum number of reconnect attempts before giving up. */
+  maxAttempts?: number;
+  /** Jitter factor (0-1) to randomize the delay. */
+  jitterFactor?: number;
+}
+
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_JITTER_FACTOR = 0.3;
+
+export interface ReconnectCallbacks {
+  /** Called when a reconnect attempt should be made. */
+  onReconnect: (attempt: number) => Promise<boolean>;
+  /** Called when all attempts are exhausted. */
+  onGiveUp: (totalAttempts: number) => void;
+  /** Called when reconnection succeeds. */
+  onSuccess: (attempt: number) => void;
+}
+
+/**
+ * Manages reconnection with exponential backoff and jitter.
+ *
+ * Delay formula: min(baseDelay * 2^attempt + jitter, maxDelay)
+ */
+export class ReconnectManager {
+  private _baseDelay: number;
+  private _maxDelay: number;
+  private _maxAttempts: number;
+  private _jitterFactor: number;
+  private _attempt = 0;
+  private _callbacks: ReconnectCallbacks;
+  private _timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  private _active = false;
+
+  constructor(callbacks: ReconnectCallbacks, config?: ReconnectConfig) {
+    this._callbacks = callbacks;
+    this._baseDelay = config?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    this._maxDelay = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    this._maxAttempts = config?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this._jitterFactor = config?.jitterFactor ?? DEFAULT_JITTER_FACTOR;
+  }
+
+  get attempt(): number {
+    return this._attempt;
+  }
+
+  get isActive(): boolean {
+    return this._active;
+  }
+
+  /** Calculate delay for the current attempt with exponential backoff + jitter. */
+  calculateDelay(attempt: number): number {
+    const exponentialDelay = this._baseDelay * Math.pow(2, attempt);
+    const jitter = exponentialDelay * this._jitterFactor * Math.random();
+    return Math.min(exponentialDelay + jitter, this._maxDelay);
+  }
+
+  /** Start the reconnection process. */
+  start(): void {
+    if (this._active) return;
+    this._active = true;
+    this._attempt = 0;
+    this._scheduleAttempt();
+  }
+
+  /** Stop the reconnection process. */
+  stop(): void {
+    this._active = false;
+    if (this._timeoutHandle) {
+      clearTimeout(this._timeoutHandle);
+      this._timeoutHandle = null;
+    }
+  }
+
+  /** Reset the attempt counter (e.g., after a successful connection). */
+  reset(): void {
+    this._attempt = 0;
+    this.stop();
+  }
+
+  /** Schedule the next reconnect attempt. */
+  private _scheduleAttempt(): void {
+    if (!this._active) return;
+
+    if (this._attempt >= this._maxAttempts) {
+      this._active = false;
+      this._callbacks.onGiveUp(this._attempt);
+      return;
+    }
+
+    const delay = this.calculateDelay(this._attempt);
+
+    this._timeoutHandle = setTimeout(async () => {
+      if (!this._active) return;
+
+      this._attempt++;
+      try {
+        const success = await this._callbacks.onReconnect(this._attempt);
+        if (success) {
+          this._active = false;
+          this._callbacks.onSuccess(this._attempt);
+        } else {
+          this._scheduleAttempt();
+        }
+      } catch {
+        this._scheduleAttempt();
+      }
+    }, delay);
+  }
+}

package/src/payments/balance-manager.ts

@@ -0,0 +1,77 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { WalletInfo, Transaction, TransactionType } from './types.js';
+
+export interface UnifiedBalance {
+  cryptoUSDC: number;
+  inEscrowUSDC: number;
+  totalUSD: number;
+}
+
+export class BalanceManager {
+  private transactions: Transaction[] = [];
+
+  getBalance(
+    walletInfo: WalletInfo | null,
+    inEscrowUSDC: number,
+  ): UnifiedBalance {
+    const cryptoUSDC = walletInfo ? parseFloat(walletInfo.balanceUSDC) : 0;
+    const totalUSD = cryptoUSDC + inEscrowUSDC;
+
+    return {
+      cryptoUSDC,
+      inEscrowUSDC,
+      totalUSD,
+    };
+  }
+
+  recordTransaction(tx: Transaction): void {
+    this.transactions.push(tx);
+  }
+
+  getTransactionHistory(
+    filter?: TransactionType,
+    limit?: number,
+    offset?: number,
+  ): Transaction[] {
+    let result = this.transactions;
+
+    if (filter) {
+      result = result.filter((tx) => tx.type === filter);
+    }
+
+    const start = offset ?? 0;
+    const end = limit !== undefined ? start + limit : undefined;
+    return result.slice(start, end);
+  }
+
+  getTotalEarnings(since?: number): number {
+    return this.transactions
+      .filter((tx) => tx.type === 'escrow_release')
+      .filter((tx) => (since !== undefined ? tx.timestamp >= since : true))
+      .reduce((sum, tx) => sum + tx.amountUSD, 0);
+  }
+
+  getTotalSpending(since?: number): number {
+    return this.transactions
+      .filter((tx) => tx.type === 'escrow_lock')
+      .filter((tx) => (since !== undefined ? tx.timestamp >= since : true))
+      .reduce((sum, tx) => sum + tx.amountUSD, 0);
+  }
+
+  async save(configDir: string): Promise<void> {
+    await mkdir(configDir, { recursive: true });
+    const filePath = join(configDir, 'transactions.json');
+    await writeFile(filePath, JSON.stringify(this.transactions, null, 2), 'utf-8');
+  }
+
+  async load(configDir: string): Promise<void> {
+    const filePath = join(configDir, 'transactions.json');
+    try {
+      const data = await readFile(filePath, 'utf-8');
+      this.transactions = JSON.parse(data) as Transaction[];
+    } catch {
+      this.transactions = [];
+    }
+  }
+}