@antseed/node 0.1.0

package/tests/balance-manager.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { BalanceManager } from '../src/payments/balance-manager.js';
+import type { Transaction } from '../src/payments/types.js';
+import type { WalletInfo } from '../src/payments/types.js';
+
+function tmpDir(): string {
+  return path.join(os.tmpdir(), `antseed-bm-test-${randomBytes(8).toString('hex')}`);
+}
+
+const dirsToClean: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirsToClean) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {}
+  }
+  dirsToClean.length = 0;
+});
+
+function makeTx(overrides?: Partial<Transaction>): Transaction {
+  return {
+    txId: `tx-${Math.random().toString(36).slice(2)}`,
+    type: 'escrow_lock',
+    amountUSD: 10,
+    from: 'buyer',
+    to: 'seller',
+    timestamp: Date.now(),
+    status: 'confirmed',
+    ...overrides,
+  };
+}
+
+describe('BalanceManager.getBalance', () => {
+  it('should compute unified balance from crypto + escrow', () => {
+    const bm = new BalanceManager();
+    const wallet: WalletInfo = { address: '0x1', chainId: 'base-local', balanceETH: '0', balanceUSDC: '50.5' };
+    const result = bm.getBalance(wallet, 10);
+
+    expect(result.cryptoUSDC).toBeCloseTo(50.5);
+    expect(result.inEscrowUSDC).toBe(10);
+    expect(result.totalUSD).toBeCloseTo(60.5);
+  });
+
+  it('should handle null wallet', () => {
+    const bm = new BalanceManager();
+    const result = bm.getBalance(null, 0);
+    expect(result.cryptoUSDC).toBe(0);
+    expect(result.totalUSD).toBe(0);
+  });
+
+  it('should include escrow in total', () => {
+    const bm = new BalanceManager();
+    const wallet: WalletInfo = { address: '0x1', chainId: 'base-local', balanceETH: '0', balanceUSDC: '100' };
+    const result = bm.getBalance(wallet, 5);
+    expect(result.totalUSD).toBe(105);
+  });
+
+  it('should handle both null wallet and zero escrow', () => {
+    const bm = new BalanceManager();
+    const result = bm.getBalance(null, 0);
+    expect(result.totalUSD).toBe(0);
+  });
+});
+
+describe('BalanceManager.recordTransaction / getTransactionHistory', () => {
+  it('should record and retrieve transactions', () => {
+    const bm = new BalanceManager();
+    const tx = makeTx();
+    bm.recordTransaction(tx);
+
+    const history = bm.getTransactionHistory();
+    expect(history).toHaveLength(1);
+    expect(history[0]!.txId).toBe(tx.txId);
+  });
+
+  it('should filter by type', () => {
+    const bm = new BalanceManager();
+    bm.recordTransaction(makeTx({ type: 'escrow_lock' }));
+    bm.recordTransaction(makeTx({ type: 'escrow_release' }));
+    bm.recordTransaction(makeTx({ type: 'escrow_lock' }));
+
+    expect(bm.getTransactionHistory('escrow_lock')).toHaveLength(2);
+    expect(bm.getTransactionHistory('escrow_release')).toHaveLength(1);
+  });
+
+  it('should support limit and offset', () => {
+    const bm = new BalanceManager();
+    for (let i = 0; i < 10; i++) {
+      bm.recordTransaction(makeTx({ txId: `tx-${i}` }));
+    }
+
+    const page = bm.getTransactionHistory(undefined, 3, 2);
+    expect(page).toHaveLength(3);
+    expect(page[0]!.txId).toBe('tx-2');
+  });
+});
+
+describe('BalanceManager.getTotalEarnings / getTotalSpending', () => {
+  it('should sum escrow_release transactions for earnings', () => {
+    const bm = new BalanceManager();
+    bm.recordTransaction(makeTx({ type: 'escrow_release', amountUSD: 10 }));
+    bm.recordTransaction(makeTx({ type: 'escrow_release', amountUSD: 20 }));
+    bm.recordTransaction(makeTx({ type: 'escrow_lock', amountUSD: 100 }));
+
+    expect(bm.getTotalEarnings()).toBe(30);
+  });
+
+  it('should sum escrow_lock transactions for spending', () => {
+    const bm = new BalanceManager();
+    bm.recordTransaction(makeTx({ type: 'escrow_lock', amountUSD: 5 }));
+    bm.recordTransaction(makeTx({ type: 'escrow_lock', amountUSD: 15 }));
+    bm.recordTransaction(makeTx({ type: 'escrow_release', amountUSD: 100 }));
+
+    expect(bm.getTotalSpending()).toBe(20);
+  });
+
+  it('should filter by since timestamp', () => {
+    const bm = new BalanceManager();
+    const now = Date.now();
+    bm.recordTransaction(makeTx({ type: 'escrow_release', amountUSD: 10, timestamp: now - 2000 }));
+    bm.recordTransaction(makeTx({ type: 'escrow_release', amountUSD: 20, timestamp: now - 500 }));
+
+    expect(bm.getTotalEarnings(now - 1000)).toBe(20);
+    expect(bm.getTotalEarnings()).toBe(30);
+  });
+});
+
+describe('BalanceManager.save / load', () => {
+  it('should persist and restore transactions', async () => {
+    const dir = tmpDir();
+    dirsToClean.push(dir);
+
+    const bm1 = new BalanceManager();
+    bm1.recordTransaction(makeTx({ txId: 'saved-tx', amountUSD: 42 }));
+    await bm1.save(dir);
+
+    const bm2 = new BalanceManager();
+    await bm2.load(dir);
+
+    const history = bm2.getTransactionHistory();
+    expect(history).toHaveLength(1);
+    expect(history[0]!.txId).toBe('saved-tx');
+    expect(history[0]!.amountUSD).toBe(42);
+  });
+
+  it('should start fresh if load file does not exist', async () => {
+    const bm = new BalanceManager();
+    await bm.load('/nonexistent/path');
+    expect(bm.getTransactionHistory()).toEqual([]);
+  });
+});

package/tests/bootstrap.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import {
+  OFFICIAL_BOOTSTRAP_NODES,
+  parseBootstrapList,
+  mergeBootstrapNodes,
+  toBootstrapConfig,
+  type BootstrapNode,
+} from '../src/discovery/bootstrap.js';
+
+describe('OFFICIAL_BOOTSTRAP_NODES', () => {
+  it('should contain at least one node', () => {
+    expect(OFFICIAL_BOOTSTRAP_NODES.length).toBeGreaterThan(0);
+  });
+
+  it('should have valid host and port for every node', () => {
+    for (const node of OFFICIAL_BOOTSTRAP_NODES) {
+      expect(node.host).toBeTruthy();
+      expect(node.port).toBeGreaterThanOrEqual(1);
+      expect(node.port).toBeLessThanOrEqual(65535);
+    }
+  });
+});
+
+describe('parseBootstrapList', () => {
+  it('should parse valid host:port entries', () => {
+    const result = parseBootstrapList(['example.com:6881', '10.0.0.1:8080']);
+    expect(result).toEqual([
+      { host: 'example.com', port: 6881 },
+      { host: '10.0.0.1', port: 8080 },
+    ]);
+  });
+
+  it('should parse IPv6 addresses with port', () => {
+    const result = parseBootstrapList(['::1:6881']);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.host).toBe('::1');
+    expect(result[0]!.port).toBe(6881);
+  });
+
+  it('should throw on missing port', () => {
+    expect(() => parseBootstrapList(['example.com'])).toThrow('missing port');
+  });
+
+  it('should throw on invalid port (0)', () => {
+    expect(() => parseBootstrapList(['example.com:0'])).toThrow('Invalid port');
+  });
+
+  it('should throw on port > 65535', () => {
+    expect(() => parseBootstrapList(['example.com:99999'])).toThrow('Invalid port');
+  });
+
+  it('should throw on non-numeric port', () => {
+    expect(() => parseBootstrapList(['example.com:abc'])).toThrow('Invalid port');
+  });
+
+  it('should handle an empty array', () => {
+    expect(parseBootstrapList([])).toEqual([]);
+  });
+});
+
+describe('mergeBootstrapNodes', () => {
+  it('should combine two disjoint lists', () => {
+    const official: BootstrapNode[] = [{ host: 'a.com', port: 1 }];
+    const user: BootstrapNode[] = [{ host: 'b.com', port: 2 }];
+    const result = mergeBootstrapNodes(official, user);
+    expect(result).toHaveLength(2);
+  });
+
+  it('should deduplicate by host:port', () => {
+    const official: BootstrapNode[] = [{ host: 'a.com', port: 1, label: 'Official' }];
+    const user: BootstrapNode[] = [{ host: 'a.com', port: 1, label: 'User' }];
+    const result = mergeBootstrapNodes(official, user);
+    expect(result).toHaveLength(1);
+    // Official entry comes first and should win
+    expect(result[0]!.label).toBe('Official');
+  });
+
+  it('should keep user nodes that have different ports', () => {
+    const official: BootstrapNode[] = [{ host: 'a.com', port: 1 }];
+    const user: BootstrapNode[] = [{ host: 'a.com', port: 2 }];
+    const result = mergeBootstrapNodes(official, user);
+    expect(result).toHaveLength(2);
+  });
+
+  it('should return empty when both inputs are empty', () => {
+    expect(mergeBootstrapNodes([], [])).toEqual([]);
+  });
+});
+
+describe('toBootstrapConfig', () => {
+  it('should strip labels and return only host/port', () => {
+    const nodes: BootstrapNode[] = [
+      { host: 'a.com', port: 1, label: 'A' },
+      { host: 'b.com', port: 2 },
+    ];
+    const result = toBootstrapConfig(nodes);
+    expect(result).toEqual([
+      { host: 'a.com', port: 1 },
+      { host: 'b.com', port: 2 },
+    ]);
+    // Ensure label is not present
+    expect(result[0]).not.toHaveProperty('label');
+  });
+
+  it('should return empty array for empty input', () => {
+    expect(toBootstrapConfig([])).toEqual([]);
+  });
+});

package/tests/buyer-payment-manager.test.ts

@@ -0,0 +1,358 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BuyerPaymentManager, type BuyerPaymentConfig } from '../src/payments/buyer-payment-manager.js';
+import type { PaymentMux } from '../src/p2p/payment-mux.js';
+import type { Identity } from '../src/p2p/identity.js';
+import type {
+  SessionLockConfirmPayload,
+  SessionLockRejectPayload,
+  SellerReceiptPayload,
+  TopUpRequestPayload,
+} from '../src/types/protocol.js';
+import * as ed from '@noble/ed25519';
+
+// --- Helpers ---
+
+async function createTestIdentity(): Promise<Identity> {
+  const privateKey = ed.utils.randomPrivateKey();
+  const publicKey = await ed.getPublicKeyAsync(privateKey);
+  const peerId = Array.from(publicKey)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+  return { peerId: peerId as any, privateKey, publicKey };
+}
+
+function createMockPaymentMux(): PaymentMux & {
+  _sentLockAuths: any[];
+  _sentBuyerAcks: any[];
+  _sentSessionEnds: any[];
+  _sentTopUpAuths: any[];
+} {
+  const mux = {
+    _sentLockAuths: [] as any[],
+    _sentBuyerAcks: [] as any[],
+    _sentSessionEnds: [] as any[],
+    _sentTopUpAuths: [] as any[],
+    sendSessionLockAuth: vi.fn(function (this: any, payload: any) {
+      this._sentLockAuths.push(payload);
+    }),
+    sendBuyerAck: vi.fn(function (this: any, payload: any) {
+      this._sentBuyerAcks.push(payload);
+    }),
+    sendSessionEnd: vi.fn(function (this: any, payload: any) {
+      this._sentSessionEnds.push(payload);
+    }),
+    sendTopUpAuth: vi.fn(function (this: any, payload: any) {
+      this._sentTopUpAuths.push(payload);
+    }),
+    // Unused but required by type
+    sendSessionLockConfirm: vi.fn(),
+    sendSessionLockReject: vi.fn(),
+    sendSellerReceipt: vi.fn(),
+    sendTopUpRequest: vi.fn(),
+    sendDisputeNotify: vi.fn(),
+    onSessionLockAuth: vi.fn(),
+    onSessionLockConfirm: vi.fn(),
+    onSessionLockReject: vi.fn(),
+    onSellerReceipt: vi.fn(),
+    onBuyerAck: vi.fn(),
+    onSessionEnd: vi.fn(),
+    onTopUpRequest: vi.fn(),
+    onTopUpAuth: vi.fn(),
+    onDisputeNotify: vi.fn(),
+    handleFrame: vi.fn(),
+  } as unknown as PaymentMux & {
+    _sentLockAuths: any[];
+    _sentBuyerAcks: any[];
+    _sentSessionEnds: any[];
+    _sentTopUpAuths: any[];
+  };
+  return mux;
+}
+
+const DEFAULT_CONFIG: BuyerPaymentConfig = {
+  defaultLockAmountUSDC: '1000000',
+  rpcUrl: 'http://127.0.0.1:8545',
+  contractAddress: '0x5FbDB2315678afecb367f032d93F642f64180aa3',
+  usdcAddress: '0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512',
+  autoAck: true,
+  autoTopUp: true,
+  maxSessionBudgetUSDC: '10000000',
+};
+
+const SELLER_PEER_ID = 'seller-peer-0123456789abcdef';
+const SELLER_EVM_ADDRESS = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8';
+
+// --- Tests ---
+
+describe('BuyerPaymentManager', () => {
+  let identity: Identity;
+  let manager: BuyerPaymentManager;
+  let mux: ReturnType<typeof createMockPaymentMux>;
+
+  beforeEach(async () => {
+    identity = await createTestIdentity();
+    manager = new BuyerPaymentManager(identity, DEFAULT_CONFIG);
+    mux = createMockPaymentMux();
+  });
+
+  describe('initiateLock', () => {
+    it('sends SessionLockAuth with correct session ID and amount', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      expect(sessionId).toMatch(/^0x[0-9a-f]{64}$/);
+      expect(mux.sendSessionLockAuth).toHaveBeenCalledTimes(1);
+
+      const sentPayload = mux._sentLockAuths[0]!;
+      expect(sentPayload.sessionId).toBe(sessionId);
+      expect(sentPayload.lockedAmount).toBe('1000000');
+      expect(typeof sentPayload.buyerSig).toBe('string');
+      expect(sentPayload.buyerSig.length).toBeGreaterThan(0);
+
+      // Session should be in pending state
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session).toBeDefined();
+      expect(session!.status).toBe('pending');
+      expect(session!.lockedAmount).toBe(1000000n);
+    });
+
+    it('uses custom lock amount when specified', async () => {
+      await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+        '5000000',
+      );
+
+      const sentPayload = mux._sentLockAuths[0]!;
+      expect(sentPayload.lockedAmount).toBe('5000000');
+
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session!.lockedAmount).toBe(5000000n);
+    });
+  });
+
+  describe('handleLockConfirm', () => {
+    it('marks session as confirmed with tx signature', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      const payload: SessionLockConfirmPayload = {
+        sessionId,
+        txSignature: '0xabc123def456',
+      };
+
+      manager.handleLockConfirm(SELLER_PEER_ID, payload);
+
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session!.status).toBe('confirmed');
+      expect(session!.txSignature).toBe('0xabc123def456');
+      expect(manager.isLockConfirmed(SELLER_PEER_ID)).toBe(true);
+    });
+
+    it('ignores confirmation for unknown seller', () => {
+      // Should not throw
+      manager.handleLockConfirm('unknown-peer', {
+        sessionId: '0x' + 'a'.repeat(64),
+        txSignature: '0xabc',
+      });
+    });
+  });
+
+  describe('handleLockReject', () => {
+    it('removes session on rejection', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      const payload: SessionLockRejectPayload = {
+        sessionId,
+        reason: 'Insufficient buyer balance',
+      };
+
+      manager.handleLockReject(SELLER_PEER_ID, payload);
+
+      expect(manager.getSession(SELLER_PEER_ID)).toBeUndefined();
+      expect(manager.isLockRejected(SELLER_PEER_ID)).toBe(true);
+    });
+  });
+
+  describe('handleSellerReceipt (auto-ack)', () => {
+    it('auto-acknowledges receipt with Ed25519 signature', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      // Confirm the lock first
+      manager.handleLockConfirm(SELLER_PEER_ID, {
+        sessionId,
+        txSignature: '0xabc',
+      });
+
+      const receipt: SellerReceiptPayload = {
+        sessionId,
+        runningTotal: '50000',
+        requestCount: 1,
+        responseHash: 'c'.repeat(64),
+        sellerSig: 'd'.repeat(128),
+      };
+
+      await manager.handleSellerReceipt(SELLER_PEER_ID, receipt, mux);
+
+      expect(mux.sendBuyerAck).toHaveBeenCalledTimes(1);
+      const ackPayload = mux._sentBuyerAcks[0]!;
+      expect(ackPayload.sessionId).toBe(sessionId);
+      expect(ackPayload.runningTotal).toBe('50000');
+      expect(ackPayload.requestCount).toBe(1);
+      expect(typeof ackPayload.buyerSig).toBe('string');
+      expect(ackPayload.buyerSig.length).toBeGreaterThan(0);
+
+      // Session should update running total
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session!.lastRunningTotal).toBe(50000n);
+      expect(session!.lastRequestCount).toBe(1);
+      expect(session!.status).toBe('active');
+    });
+  });
+
+  describe('endSession', () => {
+    it('sends SessionEnd with ECDSA settlement signature', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      // Confirm and process a receipt
+      manager.handleLockConfirm(SELLER_PEER_ID, {
+        sessionId,
+        txSignature: '0xabc',
+      });
+
+      await manager.handleSellerReceipt(SELLER_PEER_ID, {
+        sessionId,
+        runningTotal: '100000',
+        requestCount: 3,
+        responseHash: 'c'.repeat(64),
+        sellerSig: 'd'.repeat(128),
+      }, mux);
+
+      await manager.endSession(SELLER_PEER_ID, mux, 90);
+
+      expect(mux.sendSessionEnd).toHaveBeenCalledTimes(1);
+      const endPayload = mux._sentSessionEnds[0]!;
+      expect(endPayload.sessionId).toBe(sessionId);
+      expect(endPayload.runningTotal).toBe('100000');
+      expect(endPayload.requestCount).toBe(3);
+      expect(endPayload.score).toBe(90);
+      expect(typeof endPayload.buyerSig).toBe('string');
+      expect(endPayload.buyerSig.length).toBeGreaterThan(0);
+
+      // Session should be ended
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session!.status).toBe('ended');
+    });
+  });
+
+  describe('handleTopUpRequest (sufficient balance)', () => {
+    it('auto-approves top-up when budget allows and balance sufficient', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      manager.handleLockConfirm(SELLER_PEER_ID, {
+        sessionId,
+        txSignature: '0xabc',
+      });
+
+      // Mock the escrow client to return sufficient balance
+      const mockGetBuyerAccount = vi.fn().mockResolvedValue({
+        deposited: 20000000n,
+        committed: 1000000n,
+        available: 19000000n,
+      });
+      (manager as any)._escrowClient = {
+        ...manager.escrowClient,
+        getBuyerAccount: mockGetBuyerAccount,
+      };
+
+      const request: TopUpRequestPayload = {
+        sessionId,
+        additionalAmount: '2000000',
+        currentRunningTotal: '800000',
+        currentLockedAmount: '1000000',
+      };
+
+      await manager.handleTopUpRequest(SELLER_PEER_ID, request, mux);
+
+      expect(mux.sendTopUpAuth).toHaveBeenCalledTimes(1);
+      const authPayload = mux._sentTopUpAuths[0]!;
+      expect(authPayload.sessionId).toBe(sessionId);
+      expect(authPayload.additionalAmount).toBe('2000000');
+      expect(typeof authPayload.buyerSig).toBe('string');
+
+      // Session locked amount should be updated
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session!.lockedAmount).toBe(3000000n); // 1M + 2M
+    });
+  });
+
+  describe('handleTopUpRequest (insufficient balance)', () => {
+    it('ends session when balance is insufficient for top-up', async () => {
+      const sessionId = await manager.initiateLock(
+        SELLER_PEER_ID,
+        SELLER_EVM_ADDRESS,
+        mux,
+      );
+
+      manager.handleLockConfirm(SELLER_PEER_ID, {
+        sessionId,
+        txSignature: '0xabc',
+      });
+
+      // Mock the escrow client to return insufficient balance
+      const mockGetBuyerAccount = vi.fn().mockResolvedValue({
+        deposited: 1000000n,
+        committed: 1000000n,
+        available: 0n,
+      });
+      (manager as any)._escrowClient = {
+        ...manager.escrowClient,
+        getBuyerAccount: mockGetBuyerAccount,
+      };
+
+      const request: TopUpRequestPayload = {
+        sessionId,
+        additionalAmount: '2000000',
+        currentRunningTotal: '800000',
+        currentLockedAmount: '1000000',
+      };
+
+      await manager.handleTopUpRequest(SELLER_PEER_ID, request, mux);
+
+      // Should NOT send top-up auth
+      expect(mux.sendTopUpAuth).not.toHaveBeenCalled();
+
+      // Should end the session instead
+      expect(mux.sendSessionEnd).toHaveBeenCalledTimes(1);
+      const endPayload = mux._sentSessionEnds[0]!;
+      expect(endPayload.sessionId).toBe(sessionId);
+      expect(endPayload.score).toBe(80); // default score
+
+      const session = manager.getSession(SELLER_PEER_ID);
+      expect(session!.status).toBe('ended');
+    });
+  });
+});

package/tests/connection-auth.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import * as ed from '@noble/ed25519';
+import { toPeerId } from '../src/types/peer.js';
+import { bytesToHex } from '../src/utils/hex.js';
+import {
+  NonceReplayGuard,
+  buildConnectionAuthEnvelope,
+  verifyConnectionAuthEnvelope,
+} from '../src/p2p/connection-auth.js';
+
+async function createIdentity(): Promise<{ peerId: string; privateKey: Uint8Array }> {
+  const privateKey = ed.utils.randomPrivateKey();
+  const publicKey = await ed.getPublicKeyAsync(privateKey);
+  const peerId = toPeerId(bytesToHex(publicKey));
+  return { peerId, privateKey };
+}
+
+describe('connection-auth', () => {
+  it('accepts valid signed intro auth', async () => {
+    const { peerId, privateKey } = await createIdentity();
+    const nowMs = 1_700_000_000_000;
+    const auth = buildConnectionAuthEnvelope('intro', peerId, privateKey, nowMs);
+
+    const result = verifyConnectionAuthEnvelope({
+      type: 'intro',
+      auth,
+      nowMs,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.peerId).toBe(peerId);
+  });
+
+  it('rejects payload type mismatch', async () => {
+    const { peerId, privateKey } = await createIdentity();
+    const nowMs = 1_700_000_000_000;
+    const auth = buildConnectionAuthEnvelope('intro', peerId, privateKey, nowMs);
+
+    const result = verifyConnectionAuthEnvelope({
+      type: 'hello',
+      auth,
+      nowMs,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toContain('signature');
+  });
+
+  it('rejects stale auth timestamps', async () => {
+    const { peerId, privateKey } = await createIdentity();
+    const auth = buildConnectionAuthEnvelope('hello', peerId, privateKey, 1_000);
+
+    const result = verifyConnectionAuthEnvelope({
+      type: 'hello',
+      auth,
+      nowMs: 100_000,
+      maxSkewMs: 30_000,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toContain('timestamp');
+  });
+
+  it('rejects replayed nonces when replay guard is enabled', async () => {
+    const { peerId, privateKey } = await createIdentity();
+    const guard = new NonceReplayGuard();
+    const nowMs = 1_700_000_000_000;
+    const auth = buildConnectionAuthEnvelope('intro', peerId, privateKey, nowMs);
+
+    const first = verifyConnectionAuthEnvelope({
+      type: 'intro',
+      auth,
+      nowMs,
+      replayGuard: guard,
+    });
+    const second = verifyConnectionAuthEnvelope({
+      type: 'intro',
+      auth,
+      nowMs,
+      replayGuard: guard,
+    });
+
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(false);
+    expect(second.reason).toContain('replayed');
+  });
+});