@wpelevator/tug 0.8.0 → 0.10.0

package/dist/ingress.d.ts

@@ -4,8 +4,7 @@ export declare const CADDY_CONTAINER = "tug-caddy";
 export declare const DEFAULT_CADDY_IMAGE = "caddy:2-alpine";
 export interface NodeView {
     name: string;
-    /** Reachable mesh address; null when the mesh is off or the node has not reported a key yet. */
-    overlayIp: string | null;
+    /** Operator-provided address other nodes use to reach this node's published ports. */
     address: string | null;
     lastSeenAt: string | null;
 }

package/dist/ingress.js

@@ -26,7 +26,7 @@ export function resolveServiceEndpoints(states, nodes, statuses, staleBefore) {
             const endpoints = [];
             for (const nodeName of spec.placement?.nodes || []) {
                 const node = byName.get(nodeName);
-                const address = node && (node.overlayIp || node.address);
+                const address = node?.address;
                 if (!node || !address || !node.lastSeenAt || node.lastSeenAt < staleBefore)
                     continue;
                 const serviceState = reported.get(`${nodeName}\0${state.project}`)?.serviceStates?.[service];

package/dist/live.d.ts

@@ -62,6 +62,8 @@ export interface LiveEngineOptions {
     queryTimeoutMs?: number;
 }
 /** Owns Engine API streams and their lifetimes; callers own authentication, authorization and transport backpressure. */
+/** Keeps environment variable names but not values, so routine `inspect` output does not leak secrets by accident. */
+export declare function redactInspect(inspected: Record<string, unknown>): Record<string, unknown>;
 export declare class LiveOperationEngine {
     private readonly options;
     private readonly sessions;

package/dist/live.js

@@ -48,6 +48,14 @@ function validate(value) {
         throw new Error('Invalid projects');
 }
 /** Owns Engine API streams and their lifetimes; callers own authentication, authorization and transport backpressure. */
+/** Keeps environment variable names but not values, so routine `inspect` output does not leak secrets by accident. */
+export function redactInspect(inspected) {
+    const config = inspected.Config;
+    if (!config || !Array.isArray(config.Env))
+        return inspected;
+    const Env = config.Env.map((entry) => typeof entry === 'string' ? `${entry.split('=', 1)[0]}=<redacted>` : entry);
+    return { ...inspected, Config: { ...config, Env } };
+}
 export class LiveOperationEngine {
     options;
     sessions = new Map();
@@ -155,7 +163,7 @@ export class LiveOperationEngine {
                     result = lists.flat();
                 }
                 else
-                    result = [await this.options.docker.inspectContainer(request.container)];
+                    result = [redactInspect(await this.options.docker.inspectContainer(request.container))];
                 const frame = { v: 1, type: 'live.result', sessionId: id, result };
                 if (Buffer.byteLength(JSON.stringify(frame)) > LIVE_MAX_FRAME_BYTES)
                     throw new Error('Live result exceeds serialized frame size limit');

package/dist/main.js

@@ -9,7 +9,7 @@ async function readStdin() {
     return Buffer.concat(chunks).toString('utf8');
 }
 const usage = `Usage: tug-runtime <control|agent> [command]
-  control                          run the control plane (needs TUG_PUBLIC_URL)
+  control                          run the control plane (needs TUG_CONTROL_URL)
   control issue-credential         issue an operator credential on the control-plane host (--name, --role, --replace)
   agent                            run the node agent
   agent identity                   print the CSR for this node's pending key

package/dist/node-address.d.ts

@@ -0,0 +1,2 @@
+/** An IP literal or DNS hostname with no port, brackets, whitespace or other syntax that could reach generated configuration. */
+export declare const isNodeHost: (value: unknown) => value is string;

package/dist/node-address.js

@@ -0,0 +1,6 @@
+import { isIP } from 'node:net';
+const HOST_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i;
+/** An IP literal or DNS hostname with no port, brackets, whitespace or other syntax that could reach generated configuration. */
+export const isNodeHost = (value) => typeof value === 'string' &&
+    value.length <= 253 &&
+    (isIP(value) !== 0 || value.split('.').every((label) => HOST_LABEL.test(label)));

package/dist/pki.d.ts

@@ -59,7 +59,7 @@ export interface SubjectNames {
     ip: string[];
 }
 /** The DNS names and IP addresses a server certificate covers, from the public URL plus optional extras. */
-export declare function serverNames(publicUrl: string, extras?: string[]): SubjectNames;
+export declare function serverNames(controlUrl: string, extras?: string[]): SubjectNames;
 export declare const namesKey: (names: SubjectNames) => string;
 export declare class Pki {
     readonly caPem: string;
@@ -95,7 +95,9 @@ export declare class Pki {
         notAfter: Date;
     }>;
     /** The server certificate and key for the given names. */
-    issueServer(names: SubjectNames): Promise<{
+    get controlName(): string;
+    /** The server certificate always carries the generated control name, plus the given addresses. */
+    issueServer(addresses: SubjectNames): Promise<{
         cert: string;
         key: string;
         notAfter: Date;
@@ -108,7 +110,16 @@ export declare function validateInstalledCertificate(options: {
     keyPem: string;
     uri: string;
 }): void;
-/** TLS client options pinned to the credential's CA. Verification is always against the public host, even through a tunnel. */
+/**
+ * The generated name control answers to, derived from its CA key: stable for the life of the CA and independent of any
+ * address. Control puts it in its server certificate and clients recompute it from the CA they pin, so moving control to
+ * another IP or DNS name needs no new credentials.
+ */
+export declare function controlNameFromCa(caPem: string): string;
+/**
+ * TLS client options pinned to the credential's CA. The server is verified by its generated control name, never by the
+ * address the connection goes to, so an address override (a tunnel, a private IP, a moved host) keeps full verification.
+ */
 export declare function clientTlsOptions(credential: Credential): tls.ConnectionOptions;
 /** The peer identity presented on a TLS socket, or null when none can be established. */
 export declare function peerIdentity(socket: tls.TLSSocket): {

package/dist/pki.js

@@ -149,9 +149,9 @@ export async function verifyCsr(csrPem) {
 }
 const serial = () => `0${crypto.randomBytes(15).toString('hex')}`;
 /** The DNS names and IP addresses a server certificate covers, from the public URL plus optional extras. */
-export function serverNames(publicUrl, extras = []) {
+export function serverNames(controlUrl, extras = []) {
     const names = { dns: [], ip: [] };
-    const host = new URL(publicUrl).hostname.replace(/^\[|\]$/g, '');
+    const host = new URL(controlUrl).hostname.replace(/^\[|\]$/g, '');
     for (const entry of [host, ...extras.map((e) => e.trim()).filter(Boolean)]) {
         const bucket = net.isIP(entry) ? names.ip : names.dns;
         if (!bucket.includes(entry))
@@ -280,7 +280,12 @@ export class Pki {
         return { credential, keyHash: certKeyHash(cert), notAfter };
     }
     /** The server certificate and key for the given names. */
-    async issueServer(names) {
+    get controlName() {
+        return controlNameFromCa(this.caPem);
+    }
+    /** The server certificate always carries the generated control name, plus the given addresses. */
+    async issueServer(addresses) {
+        const names = { dns: [this.controlName, ...addresses.dns], ip: addresses.ip };
         const keys = await generateKeyPair();
         const { cert, notAfter } = await this.signLeaf({
             publicKey: keys.publicKey,
@@ -301,16 +306,28 @@ export function validateInstalledCertificate(options) {
     if (!(cert.subjectAltName ?? '').split(/,\s*/).includes(`URI:${options.uri}`))
         throw new Error(`certificate does not name ${options.uri}`);
 }
-/** TLS client options pinned to the credential's CA. Verification is always against the public host, even through a tunnel. */
+/**
+ * The generated name control answers to, derived from its CA key: stable for the life of the CA and independent of any
+ * address. Control puts it in its server certificate and clients recompute it from the CA they pin, so moving control to
+ * another IP or DNS name needs no new credentials.
+ */
+export function controlNameFromCa(caPem) {
+    const spki = new crypto.X509Certificate(caPem).publicKey.export({ type: 'spki', format: 'der' });
+    return `control-${hashSpki(spki).slice(0, 12)}.tug`;
+}
+/**
+ * TLS client options pinned to the credential's CA. The server is verified by its generated control name, never by the
+ * address the connection goes to, so an address override (a tunnel, a private IP, a moved host) keeps full verification.
+ */
 export function clientTlsOptions(credential) {
-    const publicHost = new URL(credential.url).hostname.replace(/^\[|\]$/g, '');
+    const name = controlNameFromCa(credential.ca);
     return {
         ca: credential.ca,
         cert: credential.cert,
         key: credential.key,
         minVersion: 'TLSv1.3',
-        ...(net.isIP(publicHost) ? {} : { servername: publicHost }),
-        checkServerIdentity: (_host, cert) => tls.checkServerIdentity(publicHost, cert),
+        servername: name,
+        checkServerIdentity: (_host, cert) => tls.checkServerIdentity(name, cert),
     };
 }
 /** The peer identity presented on a TLS socket, or null when none can be established. */

package/dist/protocol.d.ts

@@ -165,7 +165,7 @@ export declare const ACTIVE_DEPLOYMENT_STATES: readonly ["uploading", "building"
 /** Deployment states a CLI wait loop stops on. */
 export declare const TERMINAL_DEPLOYMENT_STATES: readonly ["succeeded", "failed", "build_failed", "cancelled"];
 export type DeploymentState = (typeof ACTIVE_DEPLOYMENT_STATES)[number] | (typeof TERMINAL_DEPLOYMENT_STATES)[number];
-export type CommandType = 'diagnostics.run' | 'service.restart' | 'logs.fetch' | 'volume.delete' | 'wg.rotate-key' | 'backup.check' | 'backup.run' | 'backup.restore' | 'backup.list';
+export type CommandType = 'diagnostics.run' | 'service.restart' | 'logs.fetch' | 'volume.delete' | 'backup.check' | 'backup.run' | 'backup.restore' | 'backup.list';
 /** Commands whose helper containers need the backup destination's credentials. */
 export declare const BACKUP_COMMAND_TYPES: readonly CommandType[];
 /** `GET /agent/v1/backup/credentials`: environment for the restic helper of one running backup command. */
@@ -273,8 +273,6 @@ export type CommandResultPayload = {
     project: string;
     volume: string;
     deleted: true;
-} | {
-    publicKey: string;
 } | BackupJobResult | {
     error: string;
 };
@@ -423,8 +421,6 @@ export interface WorkResponse {
     desiredStates: DesiredState[];
     commands: Command[];
     retainedImages?: string[];
-    /** WireGuard mesh config for this node; present only when the mesh is enabled on control. */
-    network?: NetworkConfig;
     /** Healthy cross-node endpoints per project and service; present only when service DNS is enabled. */
     serviceEndpoints?: ServiceEndpoints;
     /** Edge proxy config; present only for nodes marked as ingress nodes. */
@@ -439,33 +435,11 @@ export interface WorkResponse {
  * explicit host IP (including `0.0.0.0`) are never changed.
  */
 export interface PortBinding {
-    /** The node's overlay IP with the mesh, otherwise its `address` (an IP or a hostname the agent resolves); null binds to `127.0.0.1`. */
+    /** The node's `address` (an IP or a hostname the agent resolves); null binds to `127.0.0.1`. */
     address: string | null;
     /** Per project, services whose ingress port only the managed Caddy on this node dials; that port binds to `127.0.0.1`. */
     loopback: Record<string, string[]>;
 }
-export interface WgPeer {
-    node: string;
-    publicKey: string;
-    /** `host:port` the peer can be dialed on; absent for nodes behind NAT (they dial out instead). */
-    endpoint?: string;
-    allowedIps: string[];
-    persistentKeepalive: number;
-}
-/** The `network` block of `GET /agent/v1/work`: everything an agent needs to reconcile `wg0`. */
-export interface NetworkConfig {
-    interface: string;
-    /** This node's overlay address, e.g. `10.210.0.2`. */
-    overlayIp: string;
-    /** Mesh CIDR, e.g. `10.210.0.0/16`; `overlayIp` is assigned to `wg0` with this prefix length. */
-    cidr: string;
-    listenPort: number;
-    peers: WgPeer[];
-}
-/** Body of `POST /agent/v1/wireguard/key` (also accepted as `wgPublicKey` on register and enroll). */
-export interface WgKeyRequest {
-    publicKey: string;
-}
 export interface ServiceEndpoint {
     node: string;
     address: string;
@@ -552,8 +526,6 @@ export interface NodeInfo {
     id: string;
     name: string;
     address: string | null;
-    public_address: string | null;
-    overlay_ip?: string | null;
     labels?: string[];
     status: string;
     created_at: string;
@@ -565,7 +537,6 @@ export interface IdentityRequest {
     /** `create` makes a new node (idempotent for the identical key); `replace` installs a new key on an existing node. */
     mode: 'create' | 'replace';
     address?: string;
-    publicAddress?: string;
     labels?: string[];
 }
 /** Response of `POST /api/v1/nodes/:name/identity` and `POST /agent/v1/enroll`. */
@@ -581,9 +552,6 @@ export interface IdentityResponse {
 export interface EnrollRequest {
     csr: string;
     address?: string;
-    publicAddress?: string;
-    /** Base64 WireGuard public key; the private key never leaves the node. */
-    wgPublicKey?: string;
 }
 /** Response of `POST /agent/v1/enroll`. */
 export type EnrollResponse = IdentityResponse;

package/dist/reconciler.js

@@ -41,18 +41,51 @@ async function removeByName(docker, name) {
 }
 /** Creates the project network and its volumes; volumes are never removed by reconciliation. */
 export async function ensureProjectResources(docker, project, plan) {
-    if (!(await docker.inspectNetwork(plan.network)))
+    // Check all volumes before creating resources or replacing containers. An older owned volume must
+    // never be silently replaced by a new, empty volume after the naming scheme changes.
+    for (const volume of plan.volumes) {
+        if (volume.external || (await docker.inspectVolume(volume.name)))
+            continue;
+        const volumeKey = volume.labels['tug.volume'];
+        const legacyName = `tug_${project}_${volumeKey}`;
+        const legacy = await docker.inspectVolume(legacyName);
+        if (legacy?.Labels?.[LABEL_PROJECT] === project && legacy.Labels?.['tug.volume'] === volumeKey)
+            throw new Error(`managed volume ${legacyName} uses an earlier Tug name; refusing to create empty volume ${volume.name}. Recover or copy its data before deploying`);
+    }
+    let network = await docker.inspectNetwork(plan.network);
+    if (!network) {
         await docker.createNetwork(plan.network, { [LABEL_PROJECT]: project });
+        network = await docker.inspectNetwork(plan.network);
+    }
+    if (!network)
+        throw new Error(`network ${plan.network} could not be inspected after creation`);
+    if (network && network.Labels?.[LABEL_PROJECT] !== project)
+        throw new Error(`network ${plan.network} is not owned by project ${project}`);
     for (const volume of plan.volumes) {
-        if (await docker.inspectVolume(volume.name))
+        let existing = await docker.inspectVolume(volume.name);
+        if (!existing && !volume.external) {
+            await docker.createVolume(volume.name, {
+                driver: volume.driver,
+                opts: volume.opts,
+                labels: volume.labels,
+            });
+            existing = await docker.inspectVolume(volume.name);
+        }
+        if (existing) {
+            if (!volume.external) {
+                const sameOptions = (a, b) => Object.keys(a).length === Object.keys(b).length &&
+                    Object.entries(a).every(([key, value]) => b[key] === value);
+                if (existing.Labels?.[LABEL_PROJECT] !== project ||
+                    existing.Labels?.['tug.volume'] !== volume.labels['tug.volume'] ||
+                    existing.Driver !== volume.driver ||
+                    !sameOptions(existing.Options || {}, volume.opts))
+                    throw new Error(`volume ${volume.name} does not match the project's owned volume definition`);
+            }
             continue;
+        }
         if (volume.external)
             throw new Error(`external volume ${volume.name} does not exist on this node`);
-        await docker.createVolume(volume.name, {
-            driver: volume.driver,
-            opts: volume.opts,
-            labels: volume.labels,
-        });
+        throw new Error(`volume ${volume.name} could not be inspected after creation`);
     }
 }
 /** Makes sure a service's container exists for `spec`, running, replacing any container with another hash. */

package/dist/runners.d.ts

@@ -1,7 +1 @@
-import type { RunResult } from './build.ts';
 export type HttpClient = typeof fetch;
-/** Runs a host binary (`wg`, `ip`); rejects on a non-zero exit. */
-export type HostRunner = (cmd: string, args: string[], opts?: {
-    cwd?: string;
-}) => Promise<RunResult>;
-export declare function createHostRunner(): HostRunner;

package/dist/runners.js

@@ -1,6 +1 @@
-// Injectable seams for the agent's side effects so rollout/health/secret logic can be unit-tested
-// without a real Docker daemon or control plane. Docker itself is the `DockerApi` in `docker-api.ts`.
-import { run } from "./build.js";
-export function createHostRunner() {
-    return (cmd, args, opts) => run(cmd, args, opts);
-}
+export {};

package/dist/templates/control-compose.yml

@@ -6,9 +6,8 @@ services:
     environment:
       PORT: 8443
       TUG_DATA_DIR: /data
-      TUG_PUBLIC_URL: {{PUBLIC_URL}}
+      TUG_CONTROL_URL: {{CONTROL_URL}}
       TUG_EXTRA_SANS: {{EXTRA_SANS}}
-      TUG_MESH: {{MESH}}
     ports:
       - "{{PORT}}:8443"
     volumes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Portable VPS deployments with Docker Compose",
   "repository": {
     "type": "git",

package/dist/mesh.d.ts

@@ -1,70 +0,0 @@
-import type { NetworkConfig, WgPeer } from './protocol.ts';
-import type { HostRunner } from './runners.ts';
-/** Default mesh CIDR. Chosen to avoid the integration subnet 10.89.240.0/24, Docker's 172.16/12 and common home/VPN ranges. */
-export declare const DEFAULT_MESH_CIDR = "10.210.0.0/16";
-export declare const DEFAULT_WG_PORT = 51820;
-export declare const WG_INTERFACE = "wg0";
-export declare const WG_KEEPALIVE = 25;
-export declare const WG_KEY_RE: RegExp;
-export declare const isWgKey: (value: unknown) => value is string;
-/** Public key for a base64 private key (X25519, as `wg pubkey` computes it). */
-export declare function publicKeyFromPrivate(privateKey: string): string;
-export declare function generateWgKeyPair(): {
-    privateKey: string;
-    publicKey: string;
-};
-/** Loads the node's keypair from the state dir, generating it on first use. The private key never leaves this directory. */
-export declare function ensureWgKeys(stateDir: string): Promise<{
-    privateKey: string;
-    publicKey: string;
-}>;
-export declare function rotateWgKeys(stateDir: string): Promise<{
-    privateKey: string;
-    publicKey: string;
-}>;
-/** The public key control last accepted, so the agent only re-reports when it changed. */
-export declare function readReportedKey(stateDir: string): Promise<string | null>;
-export declare function writeReportedKey(stateDir: string, publicKey: string): Promise<void>;
-export declare function ipToInt(ip: string): number;
-export declare const intToIp: (n: number) => string;
-export declare function parseCidr(cidr: string): {
-    base: number;
-    prefix: number;
-    size: number;
-};
-/** First free host address in the mesh CIDR (never the network or broadcast address). */
-export declare function allocateOverlayIp(cidr: string, used: Iterable<string>): string;
-/** `host:port`, adding the WireGuard port when the public address has none. IPv6 literals are bracketed. */
-export declare function wgEndpoint(publicAddress: string | null | undefined, port: number): string | undefined;
-/** `wg syncconf` input: interface key and port plus peers (no wg-quick-only keys such as Address). */
-export declare function renderWgConfig(privateKey: string, listenPort: number, peers: WgPeer[]): string;
-export interface AppliedPeer {
-    publicKey: string;
-    endpoint?: string;
-    allowedIps: string[];
-    keepalive: number;
-}
-export interface AppliedInterface {
-    publicKey: string;
-    listenPort: number;
-    peers: AppliedPeer[];
-}
-/** Parses `wg show <iface> dump` (tab separated; first line is the interface, then one line per peer). */
-export declare function parseWgDump(dump: string): AppliedInterface;
-export interface PeerDiff {
-    add: string[];
-    remove: string[];
-    update: string[];
-}
-/** Compares desired peers with what `wg` reports. A desired endpoint is authoritative; a peer without one keeps whatever it roamed to. */
-export declare function diffPeers(desired: WgPeer[], applied: AppliedPeer[]): PeerDiff;
-export interface MeshResult {
-    created: boolean;
-    synced: boolean;
-    diff: PeerDiff;
-}
-/**
- * Brings `wg0` in line with the control-provided network block without tearing it down: creates the
- * link and address only when missing, and calls `wg syncconf` only when keys, port or peers differ.
- */
-export declare function reconcileMesh(host: HostRunner, stateDir: string, network: NetworkConfig): Promise<MeshResult>;

package/dist/mesh.js

@@ -1,202 +0,0 @@
-// WireGuard mesh: overlay IP allocation and key handling (control), config rendering, peer diffing
-// and the idempotent `wg0` reconcile (agent). All shell-outs go through an injectable HostRunner.
-import crypto from 'node:crypto';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { ensureDir, errMessage } from "./util.js";
-/** Default mesh CIDR. Chosen to avoid the integration subnet 10.89.240.0/24, Docker's 172.16/12 and common home/VPN ranges. */
-export const DEFAULT_MESH_CIDR = '10.210.0.0/16';
-export const DEFAULT_WG_PORT = 51820;
-export const WG_INTERFACE = 'wg0';
-export const WG_KEEPALIVE = 25;
-/** Below the usual 1500 path MTU minus WireGuard's 60 byte overhead (80 with IPv6 endpoints). */
-const WG_MTU = 1420;
-// ---- Keys --------------------------------------------------------------------------------------
-export const WG_KEY_RE = /^[A-Za-z0-9+/]{43}=$/;
-export const isWgKey = (value) => typeof value === 'string' && WG_KEY_RE.test(value);
-const PKCS8_X25519_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
-/** Public key for a base64 private key (X25519, as `wg pubkey` computes it). */
-export function publicKeyFromPrivate(privateKey) {
-    const key = crypto.createPrivateKey({
-        key: Buffer.concat([PKCS8_X25519_PREFIX, Buffer.from(privateKey, 'base64')]),
-        format: 'der',
-        type: 'pkcs8',
-    });
-    const jwk = crypto.createPublicKey(key).export({ format: 'jwk' });
-    return Buffer.from(jwk.x, 'base64url').toString('base64');
-}
-export function generateWgKeyPair() {
-    const jwk = crypto.generateKeyPairSync('x25519').privateKey.export({ format: 'jwk' });
-    const privateKey = Buffer.from(jwk.d, 'base64url').toString('base64');
-    return { privateKey, publicKey: Buffer.from(jwk.x, 'base64url').toString('base64') };
-}
-const wgDir = (stateDir) => path.join(stateDir, 'wireguard');
-/** Loads the node's keypair from the state dir, generating it on first use. The private key never leaves this directory. */
-export async function ensureWgKeys(stateDir) {
-    const file = path.join(wgDir(stateDir), 'private.key');
-    try {
-        const privateKey = (await fs.readFile(file, 'utf8')).trim();
-        if (isWgKey(privateKey))
-            return { privateKey, publicKey: publicKeyFromPrivate(privateKey) };
-    }
-    catch {
-        /* first boot */
-    }
-    return rotateWgKeys(stateDir);
-}
-export async function rotateWgKeys(stateDir) {
-    const pair = generateWgKeyPair();
-    await ensureDir(wgDir(stateDir));
-    await fs.writeFile(path.join(wgDir(stateDir), 'private.key'), `${pair.privateKey}\n`, {
-        mode: 0o600,
-    });
-    return pair;
-}
-/** The public key control last accepted, so the agent only re-reports when it changed. */
-export async function readReportedKey(stateDir) {
-    try {
-        return (await fs.readFile(path.join(wgDir(stateDir), 'reported.pub'), 'utf8')).trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeReportedKey(stateDir, publicKey) {
-    await ensureDir(wgDir(stateDir));
-    await fs.writeFile(path.join(wgDir(stateDir), 'reported.pub'), `${publicKey}\n`);
-}
-// ---- Overlay addressing (control) --------------------------------------------------------------
-export function ipToInt(ip) {
-    const parts = ip.split('.').map(Number);
-    if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255))
-        throw new Error(`invalid IPv4 address ${ip}`);
-    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
-}
-export const intToIp = (n) => [n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join('.');
-export function parseCidr(cidr) {
-    const [ip, bits, extra] = cidr.split('/');
-    const prefix = Number(bits);
-    if (extra !== undefined ||
-        bits === undefined ||
-        !Number.isInteger(prefix) ||
-        prefix < 8 ||
-        prefix > 29)
-        throw new Error(`invalid mesh CIDR ${cidr} (IPv4, prefix /8 to /29)`);
-    const size = 2 ** (32 - prefix);
-    const base = (ipToInt(ip) & ~(size - 1)) >>> 0;
-    return { base, prefix, size };
-}
-/** First free host address in the mesh CIDR (never the network or broadcast address). */
-export function allocateOverlayIp(cidr, used) {
-    const { base, size } = parseCidr(cidr);
-    const taken = new Set([...used].map(ipToInt));
-    for (let offset = 1; offset < size - 1; offset++) {
-        if (!taken.has(base + offset))
-            return intToIp(base + offset);
-    }
-    throw new Error(`mesh CIDR ${cidr} has no free overlay addresses`);
-}
-/** `host:port`, adding the WireGuard port when the public address has none. IPv6 literals are bracketed. */
-export function wgEndpoint(publicAddress, port) {
-    const addr = publicAddress?.trim();
-    if (!addr)
-        return undefined;
-    if (addr.startsWith('['))
-        return /\]:\d+$/.test(addr) ? addr : `${addr}:${port}`;
-    if (addr.includes(':') && addr.split(':').length > 2)
-        return `[${addr}]:${port}`;
-    return /:\d+$/.test(addr) ? addr : `${addr}:${port}`;
-}
-// ---- Config rendering and diffing (agent) ------------------------------------------------------
-/** `wg syncconf` input: interface key and port plus peers (no wg-quick-only keys such as Address). */
-export function renderWgConfig(privateKey, listenPort, peers) {
-    const lines = ['[Interface]', `PrivateKey = ${privateKey}`, `ListenPort = ${listenPort}`];
-    for (const peer of [...peers].sort((a, b) => a.publicKey.localeCompare(b.publicKey))) {
-        lines.push('', '[Peer]', `PublicKey = ${peer.publicKey}`, `AllowedIPs = ${[...peer.allowedIps].sort().join(', ')}`);
-        if (peer.endpoint)
-            lines.push(`Endpoint = ${peer.endpoint}`);
-        lines.push(`PersistentKeepalive = ${peer.persistentKeepalive}`);
-    }
-    return `${lines.join('\n')}\n`;
-}
-/** Parses `wg show <iface> dump` (tab separated; first line is the interface, then one line per peer). */
-export function parseWgDump(dump) {
-    const [header, ...rest] = dump.split('\n').filter(Boolean);
-    const h = (header || '').split('\t');
-    return {
-        publicKey: h[1] || '',
-        listenPort: Number(h[2]) || 0,
-        peers: rest.map((line) => {
-            const f = line.split('\t');
-            return {
-                publicKey: f[0],
-                endpoint: f[2] && f[2] !== '(none)' ? f[2] : undefined,
-                allowedIps: f[3] && f[3] !== '(none)' ? f[3].split(',') : [],
-                keepalive: f[7] && f[7] !== 'off' ? Number(f[7]) : 0,
-            };
-        }),
-    };
-}
-/** Compares desired peers with what `wg` reports. A desired endpoint is authoritative; a peer without one keeps whatever it roamed to. */
-export function diffPeers(desired, applied) {
-    const have = new Map(applied.map((p) => [p.publicKey, p]));
-    const want = new Map(desired.map((p) => [p.publicKey, p]));
-    const sameSet = (a, b) => a.length === b.length && [...a].sort().every((v, i) => v === [...b].sort()[i]);
-    const diff = { add: [], remove: [], update: [] };
-    for (const [key, peer] of want) {
-        const cur = have.get(key);
-        if (!cur)
-            diff.add.push(key);
-        else if (!sameSet(peer.allowedIps, cur.allowedIps) ||
-            peer.persistentKeepalive !== cur.keepalive ||
-            (peer.endpoint && peer.endpoint !== cur.endpoint))
-            diff.update.push(key);
-    }
-    for (const key of have.keys())
-        if (!want.has(key))
-            diff.remove.push(key);
-    return diff;
-}
-/**
- * Brings `wg0` in line with the control-provided network block without tearing it down: creates the
- * link and address only when missing, and calls `wg syncconf` only when keys, port or peers differ.
- */
-export async function reconcileMesh(host, stateDir, network) {
-    const { privateKey, publicKey } = await ensureWgKeys(stateDir);
-    const iface = network.interface;
-    const prefix = parseCidr(network.cidr).prefix;
-    let created = false;
-    try {
-        await host('ip', ['link', 'show', iface]);
-    }
-    catch {
-        await host('ip', ['link', 'add', iface, 'type', 'wireguard']);
-        created = true;
-    }
-    await host('ip', ['address', 'replace', `${network.overlayIp}/${prefix}`, 'dev', iface]);
-    if (created)
-        await host('ip', ['link', 'set', 'mtu', String(WG_MTU), 'up', 'dev', iface]);
-    let applied = { publicKey: '', listenPort: 0, peers: [] };
-    if (!created) {
-        try {
-            applied = parseWgDump((await host('wg', ['show', iface, 'dump'])).out);
-        }
-        catch (e) {
-            throw new Error(`wg show ${iface} failed: ${errMessage(e)}`, { cause: e });
-        }
-    }
-    const diff = diffPeers(network.peers, applied.peers);
-    const synced = created ||
-        applied.publicKey !== publicKey ||
-        applied.listenPort !== network.listenPort ||
-        diff.add.length + diff.remove.length + diff.update.length > 0;
-    if (synced) {
-        const file = path.join(wgDir(stateDir), `${iface}.conf`);
-        await ensureDir(wgDir(stateDir));
-        await fs.writeFile(file, renderWgConfig(privateKey, network.listenPort, network.peers), {
-            mode: 0o600,
-        });
-        await host('wg', ['syncconf', iface, file]);
-    }
-    return { created, synced, diff };
-}