@antseed/node 0.1.0

package/src/p2p/handshake.ts

@@ -0,0 +1,162 @@
+import { type PeerId, toPeerId } from "../types/peer.js";
+import { MessageType } from "../types/protocol.js";
+import { ConnectionState } from "../types/connection.js";
+import { signData, verifySignature, bytesToHex } from "./identity.js";
+import type { PeerConnection } from "./connection-manager.js";
+
+/** Nonce size in bytes. */
+const NONCE_SIZE = 32;
+
+/** Handshake timeout in milliseconds. */
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+
+export interface HandshakeResult {
+  remotePeerId: PeerId;
+  verified: boolean;
+}
+
+/** Generate a random nonce for the handshake challenge. */
+function generateNonce(): Uint8Array {
+  const nonce = new Uint8Array(NONCE_SIZE);
+  crypto.getRandomValues(nonce);
+  return nonce;
+}
+
+/**
+ * Build the HandshakeInit payload:
+ *   [32 bytes pubkey] [32 bytes nonce] [64 bytes signature(nonce)]
+ */
+export async function buildHandshakeInit(
+  publicKey: Uint8Array,
+  privateKey: Uint8Array
+): Promise<{ payload: Uint8Array; nonce: Uint8Array }> {
+  const nonce = generateNonce();
+  const signature = await signData(privateKey, nonce);
+
+  const payload = new Uint8Array(32 + 32 + 64);
+  payload.set(publicKey, 0);
+  payload.set(nonce, 32);
+  payload.set(signature, 64);
+
+  return { payload, nonce };
+}
+
+/**
+ * Verify a received HandshakeInit payload.
+ * Returns the remote peer's public key and nonce if valid.
+ */
+export async function verifyHandshakeInit(
+  payload: Uint8Array
+): Promise<{ remotePubKey: Uint8Array; nonce: Uint8Array; valid: boolean }> {
+  if (payload.length !== 128) {
+    return { remotePubKey: new Uint8Array(32), nonce: new Uint8Array(32), valid: false };
+  }
+
+  const remotePubKey = payload.slice(0, 32);
+  const nonce = payload.slice(32, 64);
+  const signature = payload.slice(64, 128);
+
+  const valid = await verifySignature(remotePubKey, signature, nonce);
+
+  return { remotePubKey, nonce, valid };
+}
+
+/**
+ * Build a HandshakeAck payload:
+ *   [32 bytes pubkey] [32 bytes echo-nonce] [64 bytes signature(echo-nonce)]
+ */
+export async function buildHandshakeAck(
+  publicKey: Uint8Array,
+  privateKey: Uint8Array,
+  remoteNonce: Uint8Array
+): Promise<Uint8Array> {
+  const signature = await signData(privateKey, remoteNonce);
+
+  const payload = new Uint8Array(32 + 32 + 64);
+  payload.set(publicKey, 0);
+  payload.set(remoteNonce, 32);
+  payload.set(signature, 64);
+
+  return payload;
+}
+
+/**
+ * Verify a received HandshakeAck payload against the nonce we originally sent.
+ */
+export async function verifyHandshakeAck(
+  payload: Uint8Array,
+  originalNonce: Uint8Array
+): Promise<{ remotePubKey: Uint8Array; valid: boolean }> {
+  if (payload.length !== 128) {
+    return { remotePubKey: new Uint8Array(32), valid: false };
+  }
+
+  const remotePubKey = payload.slice(0, 32);
+  const echoNonce = payload.slice(32, 64);
+  const signature = payload.slice(64, 128);
+
+  // Verify that the echoed nonce matches what we sent
+  const nonceMatches = originalNonce.every((b, i) => b === echoNonce[i]);
+  if (!nonceMatches) {
+    return { remotePubKey, valid: false };
+  }
+
+  const valid = await verifySignature(remotePubKey, signature, echoNonce);
+  return { remotePubKey, valid };
+}
+
+/**
+ * Perform the full handshake as the initiator.
+ * Sends HandshakeInit, waits for HandshakeAck, verifies.
+ */
+export async function performHandshake(
+  conn: PeerConnection,
+  localPublicKey: Uint8Array,
+  localPrivateKey: Uint8Array,
+  sendFn: (type: MessageType, payload: Uint8Array) => void,
+  waitForMessage: (type: MessageType, timeoutMs: number) => Promise<Uint8Array>
+): Promise<HandshakeResult> {
+  const { payload, nonce } = await buildHandshakeInit(localPublicKey, localPrivateKey);
+  sendFn(MessageType.HandshakeInit, payload);
+
+  const ackPayload = await waitForMessage(MessageType.HandshakeAck, HANDSHAKE_TIMEOUT_MS);
+  const { remotePubKey, valid } = await verifyHandshakeAck(ackPayload, nonce);
+
+  const remotePeerId = toPeerId(bytesToHex(remotePubKey));
+
+  if (valid) {
+    conn.setState(ConnectionState.Authenticated);
+  } else {
+    conn.setState(ConnectionState.Failed);
+  }
+
+  return { remotePeerId, verified: valid };
+}
+
+/**
+ * Respond to a handshake as the responder.
+ * Waits for HandshakeInit, verifies, sends HandshakeAck.
+ */
+export async function respondToHandshake(
+  conn: PeerConnection,
+  localPublicKey: Uint8Array,
+  localPrivateKey: Uint8Array,
+  sendFn: (type: MessageType, payload: Uint8Array) => void,
+  waitForMessage: (type: MessageType, timeoutMs: number) => Promise<Uint8Array>
+): Promise<HandshakeResult> {
+  const initPayload = await waitForMessage(MessageType.HandshakeInit, HANDSHAKE_TIMEOUT_MS);
+  const { remotePubKey, nonce, valid } = await verifyHandshakeInit(initPayload);
+
+  if (!valid) {
+    conn.setState(ConnectionState.Failed);
+    return { remotePeerId: toPeerId(bytesToHex(remotePubKey)), verified: false };
+  }
+
+  const ackPayload = await buildHandshakeAck(localPublicKey, localPrivateKey, nonce);
+  sendFn(MessageType.HandshakeAck, ackPayload);
+
+  const remotePeerId = toPeerId(bytesToHex(remotePubKey));
+  conn.setState(ConnectionState.Authenticated);
+
+  return { remotePeerId, verified: true };
+}

package/src/p2p/ice-config.ts

@@ -0,0 +1,59 @@
+/** STUN/TURN server configuration. */
+export interface IceServer {
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+}
+
+/** Full ICE configuration for a peer connection. */
+export interface IceConfig {
+  iceServers: IceServer[];
+  iceTransportPolicy?: "all" | "relay";
+}
+
+/** Returns a sensible default ICE configuration using public STUN servers. */
+export function getDefaultIceConfig(): IceConfig {
+  return {
+    iceServers: [
+      { urls: "stun:stun.l.google.com:19302" },
+      { urls: "stun:stun1.l.google.com:19302" },
+      { urls: "stun:stun2.l.google.com:19302" },
+    ],
+    iceTransportPolicy: "all",
+  };
+}
+
+/** Extract ICE candidate type from an SDP candidate string. */
+export function extractCandidateType(
+  candidate: string
+): "host" | "srflx" | "prflx" | "relay" | "unknown" {
+  const match = candidate.match(/typ\s+(host|srflx|prflx|relay)/);
+  if (!match) return "unknown";
+  return match[1] as "host" | "srflx" | "prflx" | "relay";
+}
+
+/**
+ * Determine if TURN relay fallback is needed based on gathered candidates.
+ * Returns true if no srflx (server-reflexive) candidates were gathered,
+ * which typically indicates a symmetric NAT.
+ */
+export function needsTurnFallback(candidates: string[]): boolean {
+  const types = candidates.map(extractCandidateType);
+  const hasSrflx = types.includes("srflx");
+  const hasRelay = types.includes("relay");
+  // Need TURN if we have no server-reflexive candidates
+  // (unless we already have relay candidates working)
+  return !hasSrflx && !hasRelay;
+}
+
+/**
+ * Build a complete ICE configuration, optionally adding TURN servers.
+ * If turnServers are provided, they are appended to the default STUN servers.
+ */
+export function buildIceConfig(turnServers?: IceServer[]): IceConfig {
+  const config = getDefaultIceConfig();
+  if (turnServers && turnServers.length > 0) {
+    config.iceServers.push(...turnServers);
+  }
+  return config;
+}

package/src/p2p/identity.ts

@@ -0,0 +1,110 @@
+import * as ed from "@noble/ed25519";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import {
+  createPrivateKey,
+  createPublicKey,
+  sign as nodeSign,
+  verify as nodeVerify,
+} from "node:crypto";
+import { toPeerId, type PeerId } from "../types/peer.js";
+import { hexToBytes, bytesToHex } from "../utils/hex.js";
+
+export { hexToBytes, bytesToHex };
+
+/** Directory where identity keys are stored. */
+const CONFIG_DIR = join(homedir(), ".antseed");
+const PRIVATE_KEY_FILE = "identity.key";
+const ED25519_PKCS8_SEED_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const ED25519_SPKI_PUBLIC_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export interface Identity {
+  peerId: PeerId;
+  privateKey: Uint8Array;
+  publicKey: Uint8Array;
+}
+
+/**
+ * Load an existing identity from disk, or create and persist a new one.
+ * The private key is stored as hex in ~/.antseed/identity.key.
+ */
+export async function loadOrCreateIdentity(configDir?: string): Promise<Identity> {
+  const dir = configDir ?? CONFIG_DIR;
+  const keyPath = join(dir, PRIVATE_KEY_FILE);
+
+  try {
+    const hexKey = (await readFile(keyPath, "utf-8")).trim();
+    const privateKey = hexToBytes(hexKey);
+    const publicKey = await ed.getPublicKeyAsync(privateKey);
+    const peerId = toPeerId(bytesToHex(publicKey));
+    return { peerId, privateKey, publicKey };
+  } catch {
+    // Key doesn't exist — generate a new one.
+    const privateKey = ed.utils.randomPrivateKey();
+    const publicKey = await ed.getPublicKeyAsync(privateKey);
+    const peerId = toPeerId(bytesToHex(publicKey));
+
+    await mkdir(dir, { recursive: true });
+    await writeFile(keyPath, bytesToHex(privateKey), { mode: 0o600 });
+
+    return { peerId, privateKey, publicKey };
+  }
+}
+
+/** Sign arbitrary data with the local identity's private key. */
+export async function signData(
+  privateKey: Uint8Array,
+  data: Uint8Array
+): Promise<Uint8Array> {
+  return ed.signAsync(data, privateKey);
+}
+
+/** Verify a signature from a remote peer. */
+export async function verifySignature(
+  publicKey: Uint8Array,
+  signature: Uint8Array,
+  data: Uint8Array
+): Promise<boolean> {
+  return ed.verifyAsync(signature, data, publicKey);
+}
+
+/**
+ * Sign a UTF-8 message and return a hex-encoded Ed25519 signature.
+ * Uses Node's crypto implementation for synchronous signing.
+ */
+export function signUtf8Ed25519(privateKeySeed: Uint8Array, message: string): string {
+  const key = createPrivateKey({
+    key: Buffer.concat([ED25519_PKCS8_SEED_PREFIX, Buffer.from(privateKeySeed)]),
+    format: "der",
+    type: "pkcs8",
+  });
+  const signature = nodeSign(null, Buffer.from(message, "utf-8"), key);
+  return signature.toString("hex");
+}
+
+/**
+ * Verify a UTF-8 message against a hex-encoded Ed25519 signature.
+ */
+export function verifyUtf8Ed25519(
+  publicKeyHex: string,
+  message: string,
+  signatureHex: string
+): boolean {
+  try {
+    const publicKeyBytes = hexToBytes(publicKeyHex);
+    const key = createPublicKey({
+      key: Buffer.concat([ED25519_SPKI_PUBLIC_PREFIX, Buffer.from(publicKeyBytes)]),
+      format: "der",
+      type: "spki",
+    });
+    return nodeVerify(
+      null,
+      Buffer.from(message, "utf-8"),
+      key,
+      Buffer.from(signatureHex, "hex")
+    );
+  } catch {
+    return false;
+  }
+}

package/src/p2p/index.ts

@@ -0,0 +1,11 @@
+export { type Identity, loadOrCreateIdentity, signData, verifySignature, hexToBytes, bytesToHex, signUtf8Ed25519, verifyUtf8Ed25519 } from './identity.js';
+export { encodeFrame, decodeFrame, FrameDecoder, MessageMux, type MessageHandler } from './message-protocol.js';
+export { ConnectionManager, PeerConnection, type PeerEndpoint } from './connection-manager.js';
+export { type IceServer, type IceConfig, getDefaultIceConfig, buildIceConfig, needsTurnFallback, extractCandidateType } from './ice-config.js';
+export { KeepaliveManager, buildPongPayload, type KeepaliveConfig, type KeepaliveCallbacks, DEFAULT_PING_INTERVAL_MS, DEFAULT_PONG_TIMEOUT_MS, MAX_MISSED_PONGS } from './keepalive.js';
+export { ReconnectManager, type ReconnectConfig, type ReconnectCallbacks } from './reconnect.js';
+export { performHandshake, respondToHandshake, buildHandshakeInit, verifyHandshakeInit, buildHandshakeAck, verifyHandshakeAck, type HandshakeResult } from './handshake.js';
+export { NatTraversal, type NatMapping, type NatTraversalResult } from './nat-traversal.js';
+export { PaymentMux } from './payment-mux.js';
+export type { PaymentMessageHandler } from './payment-mux.js';
+export * from './payment-codec.js';

package/src/p2p/keepalive.ts

@@ -0,0 +1,118 @@
+/** Default keepalive interval in milliseconds. */
+export const DEFAULT_PING_INTERVAL_MS = 15_000;
+
+/** Default timeout waiting for a pong response. */
+export const DEFAULT_PONG_TIMEOUT_MS = 5_000;
+
+/** Maximum consecutive missed pongs before declaring connection dead. */
+export const MAX_MISSED_PONGS = 3;
+
+export interface KeepaliveConfig {
+  pingIntervalMs?: number;
+  pongTimeoutMs?: number;
+  maxMissedPongs?: number;
+}
+
+export interface KeepaliveCallbacks {
+  sendPing: (payload: Uint8Array) => void;
+  onDead: () => void;
+}
+
+/**
+ * Manages the keepalive (ping/pong) cycle for a peer connection.
+ *
+ * The initiator sends Ping messages at a regular interval. If no Pong
+ * is received within pongTimeoutMs, it increments the missed counter.
+ * After maxMissedPongs consecutive misses, the connection is declared dead.
+ */
+export class KeepaliveManager {
+  private _pingInterval: number;
+  private _pongTimeout: number;
+  private _maxMissedPongs: number;
+  private _missedPongs = 0;
+  private _intervalHandle: ReturnType<typeof setInterval> | null = null;
+  private _pongTimeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  private _callbacks: KeepaliveCallbacks;
+  private _lastPingTime = 0;
+  private _latencyMs = 0;
+  private _running = false;
+
+  constructor(callbacks: KeepaliveCallbacks, config?: KeepaliveConfig) {
+    this._callbacks = callbacks;
+    this._pingInterval = config?.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+    this._pongTimeout = config?.pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT_MS;
+    this._maxMissedPongs = config?.maxMissedPongs ?? MAX_MISSED_PONGS;
+  }
+
+  get missedPongs(): number {
+    return this._missedPongs;
+  }
+
+  get latencyMs(): number {
+    return this._latencyMs;
+  }
+
+  get isRunning(): boolean {
+    return this._running;
+  }
+
+  /** Start the keepalive ping cycle. */
+  start(): void {
+    if (this._running) return;
+    this._running = true;
+    this._missedPongs = 0;
+    this._sendPing();
+    this._intervalHandle = setInterval(() => this._sendPing(), this._pingInterval);
+  }
+
+  /** Stop the keepalive cycle. */
+  stop(): void {
+    this._running = false;
+    if (this._intervalHandle) {
+      clearInterval(this._intervalHandle);
+      this._intervalHandle = null;
+    }
+    if (this._pongTimeoutHandle) {
+      clearTimeout(this._pongTimeoutHandle);
+      this._pongTimeoutHandle = null;
+    }
+  }
+
+  /** Handle a received Pong message. */
+  handlePong(_payload: Uint8Array): void {
+    this._missedPongs = 0;
+    this._latencyMs = Date.now() - this._lastPingTime;
+
+    if (this._pongTimeoutHandle) {
+      clearTimeout(this._pongTimeoutHandle);
+      this._pongTimeoutHandle = null;
+    }
+  }
+
+  /** Send a ping and set up the pong timeout. */
+  private _sendPing(): void {
+    this._lastPingTime = Date.now();
+
+    // Payload is the timestamp as 8 bytes (BigUint64)
+    const payload = new Uint8Array(8);
+    const view = new DataView(payload.buffer);
+    view.setBigUint64(0, BigInt(this._lastPingTime), false);
+
+    this._callbacks.sendPing(payload);
+
+    // Set timeout for pong response
+    this._pongTimeoutHandle = setTimeout(() => {
+      this._missedPongs++;
+      if (this._missedPongs >= this._maxMissedPongs) {
+        this.stop();
+        this._callbacks.onDead();
+      }
+    }, this._pongTimeout);
+  }
+}
+
+/** Build a Pong payload echoing the Ping payload. */
+export function buildPongPayload(pingPayload: Uint8Array): Uint8Array {
+  // Echo the same payload back
+  return new Uint8Array(pingPayload);
+}

package/src/p2p/message-protocol.ts

@@ -0,0 +1,171 @@
+import {
+  MessageType,
+  type FramedMessage,
+  FRAME_HEADER_SIZE,
+  MAX_PAYLOAD_SIZE,
+} from "../types/protocol.js";
+
+/**
+ * Frame layout (9 bytes header + payload):
+ *   [0]       u8   — message type
+ *   [1..4]    u32  — message ID (big-endian)
+ *   [5..8]    u32  — payload length (big-endian)
+ *   [9..]     raw  — payload bytes
+ */
+
+/** Encode a FramedMessage into a binary buffer. */
+export function encodeFrame(msg: FramedMessage): Uint8Array {
+  if (msg.payload.length > MAX_PAYLOAD_SIZE) {
+    throw new Error(
+      `Payload too large: ${msg.payload.length} > ${MAX_PAYLOAD_SIZE}`
+    );
+  }
+
+  const frame = new Uint8Array(FRAME_HEADER_SIZE + msg.payload.length);
+  const view = new DataView(frame.buffer);
+
+  view.setUint8(0, msg.type);
+  view.setUint32(1, msg.messageId);
+  view.setUint32(5, msg.payload.length);
+  frame.set(msg.payload, FRAME_HEADER_SIZE);
+
+  return frame;
+}
+
+const VALID_MESSAGE_TYPES = new Set<number>(
+  Object.values(MessageType).filter((v): v is number => typeof v === "number"),
+);
+
+function isValidMessageType(value: number): boolean {
+  return VALID_MESSAGE_TYPES.has(value);
+}
+
+/**
+ * Decode a single FramedMessage from a binary buffer.
+ * Returns the message and the number of bytes consumed.
+ * Returns null if the buffer doesn't contain a complete frame.
+ */
+export function decodeFrame(
+  data: Uint8Array
+): { message: FramedMessage; bytesConsumed: number } | null {
+  if (data.length < FRAME_HEADER_SIZE) {
+    return null;
+  }
+
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const rawType = view.getUint8(0);
+  if (!isValidMessageType(rawType)) {
+    return null;
+  }
+  const type = rawType as MessageType;
+  const messageId = view.getUint32(1);
+  const payloadLength = view.getUint32(5);
+
+  if (payloadLength > MAX_PAYLOAD_SIZE) {
+    throw new Error(
+      `Payload length ${payloadLength} exceeds maximum ${MAX_PAYLOAD_SIZE}`
+    );
+  }
+
+  const totalLength = FRAME_HEADER_SIZE + payloadLength;
+  if (data.length < totalLength) {
+    return null; // incomplete frame
+  }
+
+  const payload = data.slice(FRAME_HEADER_SIZE, totalLength);
+
+  return {
+    message: { type, messageId, payload },
+    bytesConsumed: totalLength,
+  };
+}
+
+/**
+ * Streaming frame decoder that handles partial frames across
+ * multiple data chunks (e.g., from a DataChannel).
+ */
+export class FrameDecoder {
+  private _buffer: Uint8Array = new Uint8Array(0);
+
+  /** Feed new data and return any complete frames. */
+  feed(chunk: Uint8Array): FramedMessage[] {
+    // Append chunk to buffer
+    const newBuffer = new Uint8Array(this._buffer.length + chunk.length);
+    newBuffer.set(this._buffer, 0);
+    newBuffer.set(chunk, this._buffer.length);
+    this._buffer = newBuffer;
+
+    const messages: FramedMessage[] = [];
+
+    while (true) {
+      let result: ReturnType<typeof decodeFrame>;
+      try {
+        result = decodeFrame(this._buffer);
+      } catch {
+        this._buffer = new Uint8Array(0);
+        break;
+      }
+      if (!result) break;
+
+      messages.push(result.message);
+      this._buffer = this._buffer.slice(result.bytesConsumed);
+    }
+
+    return messages;
+  }
+
+  /** Reset the internal buffer. */
+  reset(): void {
+    this._buffer = new Uint8Array(0);
+  }
+
+  /** Number of buffered bytes not yet decoded. */
+  get bufferedBytes(): number {
+    return this._buffer.length;
+  }
+}
+
+/** Handler function for a specific message type. */
+export type MessageHandler = (msg: FramedMessage) => void | Promise<void>;
+
+/**
+ * Message multiplexer — routes decoded frames to registered handlers.
+ */
+export class MessageMux {
+  private _handlers = new Map<MessageType, MessageHandler[]>();
+  private _defaultHandler: MessageHandler | null = null;
+
+  /** Register a handler for a specific message type. */
+  on(type: MessageType, handler: MessageHandler): void {
+    const existing = this._handlers.get(type) ?? [];
+    existing.push(handler);
+    this._handlers.set(type, existing);
+  }
+
+  /** Remove a handler for a specific message type. */
+  off(type: MessageType, handler: MessageHandler): void {
+    const existing = this._handlers.get(type);
+    if (!existing) return;
+    const idx = existing.indexOf(handler);
+    if (idx !== -1) {
+      existing.splice(idx, 1);
+    }
+  }
+
+  /** Set a default handler for unregistered message types. */
+  setDefaultHandler(handler: MessageHandler): void {
+    this._defaultHandler = handler;
+  }
+
+  /** Dispatch a framed message to registered handlers. */
+  async dispatch(msg: FramedMessage): Promise<void> {
+    const handlers = this._handlers.get(msg.type);
+    if (handlers && handlers.length > 0) {
+      for (const handler of handlers) {
+        await handler(msg);
+      }
+    } else if (this._defaultHandler) {
+      await this._defaultHandler(msg);
+    }
+  }
+}