@aria-cli/wireguard 1.0.18 → 1.0.23

package/dist/peer-discovery.d.ts

@@ -1,132 +0,0 @@
-/**
- * PeerDiscoveryService — periodic peer discovery via coordination server.
- *
- * Polls the coordination server every 60s, diffs against local PeerRegistry,
- * refreshes remote endpoints for known peers, and auto-starts/stops tunnels for
- * new/disappeared peers. Emits events for peer join/leave so higher-level systems
- * can react.
- *
- * Architecture:
- *   PeerDiscoveryService → POST /api/v1/network/peers → diff local →
- *   applyPeerRepair/startTunnel/stopTunnel
- *   STUN refreshes OUR endpoint. Peer discovery refreshes REMOTE peer endpoints.
- *
- * Limitation: The coordination server is a peer's ARIA HTTP server, NOT an
- * independent highly-available service. If the coordination server peer goes
- * offline, discovery stops for the entire mesh. For production meshes (>10 peers),
- * deploy a dedicated coordination service at the coordinationUrl.
- *
- * Discovery only auto-connects peers that have completed the invite flow (PSK
- * exchange). Unknown peers emit "peerDiscoveredUnknown" for the daemon to handle.
- */
-import { EventEmitter } from "node:events";
-import { type NodeId, type PeerTransportId, type LegacyPeerRegistryStatus, type NetworkManagerRef, type NetworkPeerRepairFailureRef, type NetworkPeerRepairResultRef } from "@aria-cli/tools";
-/** Peer info returned from the coordination server */
-export interface DiscoveredPeer {
-    nodeId: NodeId;
-    transportPublicKey: PeerTransportId;
-    displayNameSnapshot?: string;
-    status: LegacyPeerRegistryStatus;
-    endpointHost: string | null;
-    endpointPort: number | null;
-    endpointRevision?: number;
-    updatedAt?: number;
-    lastHandshake?: number | null;
-    createdAt?: number;
-}
-/** Minimal interface for the NetworkManager dependency */
-type PeerDiscoveryRepairInput = Parameters<NonNullable<NetworkManagerRef["applyPeerRepair"]>>[0];
-export interface PeerDiscoveryNetworkManager {
-    startTunnel(nodeId: NodeId): Promise<void>;
-    stopTunnel(nodeId: NodeId): void;
-    heartbeat(nodeId: NodeId): boolean;
-    applyPeerRepair(input: PeerDiscoveryRepairInput): NetworkPeerRepairResultRef | NetworkPeerRepairFailureRef;
-    readonly activeTunnelCount: number;
-}
-/** Envelope signer callback — creates a MutationEnvelope for a given operation */
-export type EnvelopeSigner = (operation: string, payload: Record<string, unknown>) => Record<string, unknown>;
-export interface PeerDiscoveryOptions {
-    /** NetworkManager for tunnel lifecycle */
-    networkManager: PeerDiscoveryNetworkManager;
-    /** Durable local node identity used on the control plane */
-    nodeId: NodeId;
-    /** Coordination server URL (e.g., https://leader:3000) */
-    coordinationUrl: string;
-    /** Our display snapshot for registration heartbeats */
-    displayNameSnapshot: string;
-    /** AbortSignal for clean shutdown */
-    signal?: AbortSignal;
-    /** Poll interval in ms (default: 60_000) */
-    pollIntervalMs?: number;
-    /** Max peers to auto-connect (respects NetworkManager.MAX_PEERS=128) */
-    maxPeers?: number;
-    /** Ed25519 signing public key (base64 SPKI DER) */
-    signingPublicKey: string;
-    /** Ed25519 signing private key (base64 PKCS#8 DER) */
-    signingPrivateKey: string;
-    /** Envelope signer for MutationEnvelope-based auth */
-    envelopeSigner: EnvelopeSigner;
-    /** Optional pinned CA cert for HTTPS coordination control-plane traffic. */
-    coordinationCaCert?: string;
-    /** Optional expected TLS identity for the coordination control plane. */
-    coordinationTlsIdentity?: string;
-    /** Read the runtime-owned local endpoint that should be published through register heartbeats. */
-    getLocalRegistrationState?: () => {
-        endpointHost?: string;
-        endpointPort?: number;
-        endpointRevision?: number;
-    } | null | undefined;
-}
-/**
- * Periodic peer discovery service.
- *
- * Polls coordination server, diffs against local state, auto-manages tunnels.
- * Emits: "peerJoined" (displayNameSnapshot|nodeId, nodeId), "peerLeft" (displayNameSnapshot|nodeId, nodeId), "error" (Error)
- */
-export declare class PeerDiscoveryService extends EventEmitter {
-    private interval;
-    private readonly networkManager;
-    private readonly nodeId;
-    private readonly coordinationUrl;
-    private readonly displayNameSnapshot;
-    private readonly signal?;
-    private readonly pollIntervalMs;
-    private readonly maxPeers;
-    private readonly signingPublicKey;
-    private readonly signingPrivateKey;
-    private readonly envelopeSigner;
-    private readonly coordinationCaCert?;
-    private readonly coordinationTlsIdentity?;
-    private readonly getLocalRegistrationState?;
-    /** Track known remote peers by durable peer principal for diff */
-    private knownRemotePeers;
-    private pollInFlight;
-    private readonly initialSyncPromise;
-    private resolveInitialSync;
-    private initialSyncSettled;
-    private stopped;
-    constructor(options: PeerDiscoveryOptions);
-    /** Start periodic peer discovery */
-    start(): void;
-    /** Resolve once the first discovery poll attempt finishes (success or failure). */
-    waitForInitialSync(): Promise<void>;
-    /** Stop periodic discovery */
-    stop(): void;
-    private schedulePoll;
-    private reportError;
-    private peerEndpointRevision;
-    private peerFreshness;
-    private classifyRepairOutcome;
-    private repairInputForPeer;
-    private postControlPlane;
-    /** Force an immediate heartbeat to the coordination server */
-    heartbeat(): Promise<void>;
-    private parseDiscoveredPeer;
-    /** Single poll cycle: heartbeat + discover + diff + act */
-    poll(): Promise<void>;
-    /** Fetch peers from coordination server using envelope-authenticated POST only. */
-    private fetchPeers;
-    /** Reconcile remote peers with local state */
-    private reconcile;
-}
-export {};

package/dist/resilient-tunnel.d.ts

@@ -1,69 +0,0 @@
-/**
- * ResilientTunnel — wraps SecureTunnel with dead peer detection, auto-reconnection,
- * and outbound message queuing.
- *
- * State machine:
- *   CONNECTING → HANDSHAKING → CONNECTED → DISCONNECTED → RECONNECTING → HANDSHAKING → CONNECTED
- *                                  ↓
- *                               DEAD (max retries exhausted)
- */
-import { EventEmitter } from "node:events";
-import { SecureTunnel, type SecureTunnelOptions } from "./tunnel.js";
-export type TunnelState = "connecting" | "handshaking" | "connected" | "disconnected" | "reconnecting" | "dead";
-export interface ResilientTunnelStats {
-    state: TunnelState;
-    reconnections: number;
-    reconnectAttempts: number;
-    queueDepth: number;
-    queueBytes: number;
-}
-export declare class ResilientTunnel extends EventEmitter {
-    private options;
-    private tunnel;
-    private _state;
-    private queue;
-    private queueBytes;
-    private reconnectAttempts;
-    private reconnectTimer;
-    private deadPeerTimer;
-    private lastPacketAt;
-    private reconnections;
-    private awaitingReplayReadiness;
-    private stopped;
-    static readonly MAX_QUEUE_SIZE = 1000;
-    static readonly MAX_QUEUE_BYTES = 1048576;
-    static readonly MAX_RECONNECT_ATTEMPTS = 10;
-    static readonly DEAD_PEER_TIMEOUT_MS = 300000;
-    static readonly MAX_BACKOFF_MS = 60000;
-    static readonly BASE_BACKOFF_MS = 1000;
-    constructor(options: SecureTunnelOptions);
-    /** Start the resilient tunnel — creates underlying SecureTunnel and waits for remote proof before CONNECTED */
-    start(): Promise<number>;
-    /** Send plaintext through the tunnel. Queues if not yet connected or reconnecting, throws if dead. */
-    sendPlaintext(data: Buffer): void;
-    /** Stop the tunnel permanently */
-    stop(): void;
-    /** Whether the tunnel is actively connected */
-    get isActive(): boolean;
-    /** Current tunnel state */
-    getState(): TunnelState;
-    /** Stats including reconnection count and queue depth */
-    getStats(): ResilientTunnelStats;
-    /** Get the underlying SecureTunnel (for event wiring, e.g. "plaintext") */
-    getInnerTunnel(): SecureTunnel | null;
-    private setState;
-    private requestSessionProof;
-    private createAndStartTunnel;
-    private disposeCurrentTunnel;
-    private handleDisconnect;
-    private promoteInitialReady;
-    private promoteReconnectReady;
-    private finalizeReconnect;
-    private attemptReconnect;
-    private resetDeadPeerTimer;
-    private clearDeadPeerTimer;
-    private clearTimers;
-    private enqueue;
-    private purgeExpired;
-    private flushQueue;
-}

package/dist/route-ownership.d.ts

@@ -1,22 +0,0 @@
-export type DirectRouteClaimStatus = "active" | "pending" | "pending_tunnel" | "pending_verification" | "revoked";
-export interface DirectRouteClaim {
-    publicKey: string;
-    nodeId?: string | null;
-    status: DirectRouteClaimStatus;
-    endpointHost?: string | null;
-    endpointPort?: number | null;
-    endpointRevision?: number | null;
-    createdAt: number;
-    updatedAt?: number | null;
-}
-export interface DirectRouteOwnershipDecision {
-    routeKey: string | null;
-    ownership: "current" | "superseded";
-    ownerPublicKey: string;
-    supersededByPublicKey?: string;
-}
-export declare function getDirectRouteKey(input: {
-    endpointHost?: string | null;
-    endpointPort?: number | null;
-}): string | null;
-export declare function resolveDirectRouteOwnership(claims: readonly DirectRouteClaim[]): Map<string, DirectRouteOwnershipDecision>;

package/dist/tunnel.d.ts

@@ -1,140 +0,0 @@
-/**
- * SecureTunnel — TypeScript transport layer wrapping the boringtun native addon.
- *
- * Manages the UDP socket, port forwarding (plaintext ↔ encrypted), and the
- * 250ms timer loop that drives WireGuard's internal state machine. The native
- * addon handles all cryptographic operations; this module handles I/O.
- *
- * Usage:
- *   const tunnel = new SecureTunnel({ privateKey, peerPublicKey, listenPort });
- *   await tunnel.start();
- *   tunnel.sendPlaintext(Buffer.from("hello"));
- *   tunnel.on("plaintext", (data) => console.log("received:", data));
- *   tunnel.stop();
- */
-import * as dgram from "node:dgram";
-import { EventEmitter } from "node:events";
-export interface PacketHandlingDisposition {
-    handled: boolean;
-    peerPublicKey: string;
-    outcome: "no_tunnel" | "done" | "write_to_network" | "write_to_tunnel" | "decrypt_error" | "decrypt_exception";
-    errorDetail?: string;
-}
-/**
- * External shared UDP socket interface.
- * When provided, SecureTunnel uses this socket instead of creating its own.
- * This enables the single-port WireGuard architecture where NetworkManager
- * owns ONE socket for ALL peers (like the real WireGuard kernel module).
- */
-export interface ExternalSocket {
-    /** Send encrypted data to a peer through the shared socket */
-    send(data: Buffer, port: number, host: string, cb?: (err?: Error) => void): void;
-    /** The bound port of the shared socket (returned from start()) */
-    port: number;
-    /**
-     * Subscribe to incoming packets on the shared socket.
-     * The handler receives ALL packets — the tunnel must check if each packet
-     * belongs to it (via decrypt) and report whether it consumed the packet.
-     * Returns an unsubscribe function.
-     */
-    onPacket(handler: (msg: Buffer, rinfo: dgram.RemoteInfo) => PacketHandlingDisposition): () => void;
-}
-export interface SecureTunnelOptions {
-    /** Base64-encoded X25519 private key */
-    privateKey: string;
-    /** Base64-encoded X25519 peer public key */
-    peerPublicKey: string;
-    /** Optional preshared key (base64) */
-    presharedKey?: string;
-    /** Persistent keepalive interval in seconds (0 = disabled, default: 25) */
-    keepalive?: number;
-    /** Local UDP port for WireGuard protocol (default: random high port) */
-    listenPort?: number;
-    /** Peer's endpoint host */
-    peerHost?: string;
-    /** Peer's endpoint port */
-    peerPort?: number;
-    /** Tunnel-internal source IPv4 address as 32-bit integer (default: 10.0.0.1 = 0x0a000001) */
-    tunnelSrcIp?: number;
-    /** Tunnel-internal destination IPv4 address as 32-bit integer (default: 10.0.0.2 = 0x0a000002) */
-    tunnelDstIp?: number;
-    /**
-     * External shared UDP socket. When provided, the tunnel uses this socket
-     * instead of creating its own. This is the single-port WireGuard model
-     * where NetworkManager owns ONE socket for ALL peers.
-     */
-    externalSocket?: ExternalSocket;
-}
-export interface TunnelStats {
-    /** Bytes sent through the tunnel */
-    bytesSent: number;
-    /** Bytes received through the tunnel */
-    bytesReceived: number;
-    /** Number of successful handshakes */
-    handshakes: number;
-    /** Timestamp of last handshake (epoch ms) */
-    lastHandshake: number | null;
-    /** Whether the tunnel is currently active */
-    active: boolean;
-}
-/**
- * Encrypted UDP tunnel backed by boringtun.
- *
- * Events:
- *   - "plaintext": decrypted data received from peer
- *   - "handshake": WireGuard handshake completed
- *   - "error": tunnel or socket error
- *   - "close": tunnel stopped
- */
-/**
- * Wrap arbitrary data in a minimal valid IPv4 packet for boringtun layer-3 tunnel.
- *
- * WireGuard is a layer-3 VPN — boringtun validates that decrypted plaintext is a
- * valid IPv4 or IPv6 packet before returning it. Raw bytes are rejected with
- * "InvalidPacket". This helper constructs a minimal 20-byte IPv4 header wrapping
- * the given payload.
- */
-declare function wrapIpv4(payload: Buffer, srcIp?: number, dstIp?: number): Buffer;
-/**
- * Extract payload from an IPv4 packet by reading the IHL field.
- * Optionally validates that the source IP matches the expected peer IP.
- */
-declare function unwrapIpv4(packet: Buffer, expectedSourceIp?: number): Buffer;
-export { wrapIpv4, unwrapIpv4 };
-export declare class SecureTunnel extends EventEmitter {
-    private options;
-    private socket;
-    private tickTimer;
-    private tunnel;
-    private stats;
-    /** Tracks whether the first successful decrypt has occurred (handshake completed) */
-    private handshakeCompleted;
-    private peerHost;
-    private peerPort;
-    /** Unsubscribe function for external socket mode */
-    private externalSocketUnsub;
-    constructor(options: SecureTunnelOptions);
-    /** Start the tunnel — binds UDP socket, creates WireGuard tunnel, starts timer */
-    start(): Promise<number>;
-    /**
-     * Handle an incoming encrypted packet. Called either by our own socket
-     * or by the shared socket dispatcher (in shared socket mode).
-     *
-     * Returns true if this tunnel consumed the packet, false otherwise.
-     */
-    handleIncomingPacket(msg: Buffer, rinfo: dgram.RemoteInfo): boolean;
-    private classifyIncomingPacket;
-    /** Whether the tunnel is currently active */
-    get isActive(): boolean;
-    /** Send plaintext data through the encrypted tunnel */
-    sendPlaintext(data: Buffer): void;
-    /** Set or update the peer endpoint */
-    setPeerEndpoint(host: string, port: number): void;
-    /** Get tunnel statistics */
-    getStats(): TunnelStats;
-    private markAuthenticatedSessionProof;
-    /** Stop the tunnel — closes socket (or unsubscribes from shared), stops timer */
-    stop(): void;
-    /** Handle a WireGuard tunnel result */
-    private handleResult;
-}

package/index.d.ts

@@ -1,59 +0,0 @@
-/* auto-generated by NAPI-RS */
-/* eslint-disable */
-export declare class WireGuardTunnel {
-  /**
-   * Create a new WireGuard tunnel.
-   *
-   * private_key: base64-encoded 32-byte X25519 private key
-   * peer_public_key: base64-encoded 32-byte X25519 public key
-   * preshared_key: optional base64-encoded 32-byte preshared key
-   * keepalive: persistent keepalive interval in seconds (0 = disabled)
-   * index: tunnel index for session disambiguation (random if not provided)
-   */
-  constructor(privateKey: string, peerPublicKey: string, presharedKey?: string | undefined | null, keepalive?: number | undefined | null, index?: number | undefined | null)
-  /**
-   * Encrypt plaintext data for sending over the network.
-   * Returns { op: "write_to_network", data: Buffer } on success.
-   */
-  encrypt(src: Buffer): WireGuardResult
-  /**
-   * Decrypt data received from the network.
-   * Returns { op: "write_to_tunnel", data: Buffer } on success.
-   *
-   * `src_addr` is the IP address of the packet's sender. It is required by
-   * boringtun's rate limiter for cookie-based DoS protection on handshake
-   * messages. Passing null/undefined causes handshake packets to be rejected
-   * once the rate limiter is under load (after ~10 handshakes).
-   *
-   * The dst buffer must be large enough for chained output: when a handshake
-   * response (92 bytes) is decapsulated, boringtun may chain a queued transport
-   * packet whose size depends on the original encrypt() payload, not the
-   * handshake response size. We use max(src.len(), 65536) to handle payloads
-   * up to the WireGuard maximum segment size.
-   */
-  decrypt(src: Buffer, srcAddr?: string | undefined | null): WireGuardResult
-  /**
-   * Timer tick — must be called every ~250ms.
-   * May produce keepalive or handshake initiation packets.
-   */
-  tick(): WireGuardResult
-}
-
-export declare function generateKeypair(): KeyPair
-
-/**
- * Generate a new X25519 keypair for WireGuard.
- * Returns { publicKey: string, privateKey: string } (base64-encoded).
- */
-export interface KeyPair {
-  publicKey: string
-  privateKey: string
-}
-
-/** Result from a tunnel operation. */
-export interface WireGuardResult {
-  /** "ok" | "done" | "write_to_network" | "write_to_tunnel" | "error" */
-  op: string
-  /** Output data (if any) */
-  data?: Buffer
-}