@antseed/node 0.1.0 → 0.1.1

package/src/p2p/nat-traversal.ts

@@ -1,169 +0,0 @@
-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

@@ -1,165 +0,0 @@
-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

@@ -1,153 +0,0 @@
-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

@@ -1,117 +0,0 @@
-/** 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

@@ -1,77 +0,0 @@
-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 = [];
-    }
-  }
-}