@wpelevator/tug 0.8.0 → 0.9.0

package/README.md

@@ -56,19 +56,19 @@ Install the CLI (Node >= 22.18), or run it without installing through `npx @wpel
 
 ```bash
 npm install -g @wpelevator/tug
+tug control-install root@203.0.113.5 --advertise-url https://203.0.113.5:8443 --install-docker
+tug init tug-root.credential.json
+tug node-install root@198.51.100.7 --name app1 --install-docker
+tug deploy -f docker-compose.yml
 ```
 
-The CLI installs the matching `ghcr.io/wpelevator/tug:<version>` image on your hosts.
+The CLI installs the matching `ghcr.io/wpelevator/tug:<version>` image on your hosts. Control serves mutual TLS directly on its port (`8443`): every operator, CI job and node authenticates with a certificate from a private CA created at install, and clients verify a name generated from that CA, so the address can be a bare IP and can change later. Do not terminate TLS in front of it.
 
-1. Install the control plane: `tug control-install root@control.example.com --public-url https://control.example.com:8443 --install-docker`. The flag installs missing Docker Engine and the Compose plugin that runs the control container on supported Debian, Ubuntu, Fedora and RHEL-compatible hosts; omit it when Docker is ready. Control serves mutual TLS directly on its published port (`8443`); do not terminate TLS in front of it ([Control plane](docs/control-plane.md#authentication-and-pki)).
-2. Point the CLI at it: `tug init tug-root.credential.json` (the file `control-install` wrote). It writes `tug.yml` (commit it, and list your servers in it), copies the credential to a `0600` file in `~/.config/tug/credentials/` and points the git-ignored `tug.local.yml` at it; see [CLI reference](docs/cli.md#config-file).
-3. Set the secrets your services need: `tug secret-set DB_PASSWORD`.
-4. Add nodes with `tug node-install root@app1.example.com --name app1 --install-docker`, or run `tug node-prepare-enrollment --name app1` and then the printed Docker command on the host. Nodes need Docker Engine only. For a bare cloud host, `tug node-prepare-enrollment --name app1 --install-docker` prints cloud-init user-data.
-5. Deploy: `tug deploy -f docker-compose.yml`. It waits until every node reports the new desired-state revision healthy.
-6. Operate with `tug status`, `events`, `exec`, `run`, `logs`, `ps`, `inspect`, `restart`, `rollback`, `backup-run`, `restore` and `doctor`. Create more operator credentials for CI and teammates with `tug credential-create`.
+The full walkthrough, including nodes you cannot SSH to (`tug node-prepare-enrollment`), CI credentials (`tug credential-create`), moving the control plane and recovery, is in [Getting started](docs/getting-started.md).
 
 ## Documentation
 
+- [Getting started](docs/getting-started.md): install control, add nodes, deploy, give CI a credential, move control, recover.
 - [Terminology](docs/terminology.md): core concepts, the naming review (which recommendations are implemented), industry comparisons and the remaining proposed interface improvements.
 - [Architecture](docs/architecture.md): components, reconciliation, workflow diagrams, secrets and runtime paths.
 - [Compose extensions](docs/compose.md): `x-tug` placement, health checks, volumes and limitations.

package/dist/build.d.ts

@@ -5,7 +5,13 @@ export interface RunResult {
 export interface RunOptions {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /** Kills the process after this long; defaults to {@link RUN_TIMEOUT_MS}. */
+    timeoutMs?: number;
 }
+/** Longest a child process may run before it is killed, so a stalled build cannot hold the control writer forever. */
+export declare const RUN_TIMEOUT_MS: number;
+/** Per-stream cap on retained output; the tail is kept because failures are reported last. */
+export declare const RUN_OUTPUT_LIMIT: number;
 export interface BuildSpec {
     context?: string;
     dockerfile?: string;

package/dist/build.js

@@ -4,16 +4,36 @@ import path from 'node:path';
 import * as tar from 'tar';
 import { scanArchive } from "./archive.js";
 import { ensureDir, exists } from "./util.js";
+/** Longest a child process may run before it is killed, so a stalled build cannot hold the control writer forever. */
+export const RUN_TIMEOUT_MS = 30 * 60 * 1000;
+/** Per-stream cap on retained output; the tail is kept because failures are reported last. */
+export const RUN_OUTPUT_LIMIT = 1024 * 1024;
+const tail = (text, chunk) => (text + chunk).length > RUN_OUTPUT_LIMIT ? (text + chunk).slice(-RUN_OUTPUT_LIMIT) : text + chunk;
 export function run(cmd, args, opts = {}) {
     return new Promise((resolve, reject) => {
-        const p = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] });
+        const { timeoutMs = RUN_TIMEOUT_MS, ...spawnOptions } = opts;
+        const p = spawn(cmd, args, { ...spawnOptions, stdio: ['ignore', 'pipe', 'pipe'] });
         let out = '', err = '';
-        p.stdout.on('data', (d) => (out += d));
-        p.stderr.on('data', (d) => (err += d));
-        p.on('error', reject);
-        p.on('close', (code) => code === 0
-            ? resolve({ out, err })
-            : reject(new Error(`${cmd} ${args.join(' ')} failed (${code})\n${out}\n${err}`)));
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            p.kill('SIGKILL');
+        }, timeoutMs);
+        p.stdout.on('data', (d) => (out = tail(out, String(d))));
+        p.stderr.on('data', (d) => (err = tail(err, String(d))));
+        p.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        p.on('close', (code) => {
+            clearTimeout(timer);
+            if (timedOut)
+                reject(new Error(`${cmd} ${args.join(' ')} timed out after ${timeoutMs} ms\n${out}\n${err}`));
+            else if (code === 0)
+                resolve({ out, err });
+            else
+                reject(new Error(`${cmd} ${args.join(' ')} failed (${code})\n${out}\n${err}`));
+        });
     });
 }
 export async function unpackContext(tarball, dest) {

package/dist/cli-build.js

@@ -32,7 +32,7 @@ export function sourceArchiveFilter(entry, configPaths, ignores) {
 /** Credential documents written by `control-install --credential-out` (default `tug-root.credential.json`). */
 const CREDENTIAL_FILE = /\.credential\.json$/;
 const ignoreCache = new WeakMap();
-/** Translates one `.dockerignore` pattern: `*` and `?` stay within a path segment, `**` crosses them. */
+/** Translates one `.dockerignore` pattern: `*`, `?` and `[...]` classes stay within a path segment, `**` crosses them. */
 function ignorePattern(pattern) {
     let source = '';
     for (let i = 0; i < pattern.length; i++) {
@@ -51,6 +51,13 @@ function ignorePattern(pattern) {
             source += '[^/]*';
         else if (char === '?')
             source += '[^/]';
+        else if (char === '[' && pattern.indexOf(']', i + 2) > 0) {
+            const close = pattern.indexOf(']', i + 2);
+            const body = pattern.slice(i + 1, close);
+            const negated = body[0] === '^' || body[0] === '!';
+            source += `[${negated ? '^' : ''}${(negated ? body.slice(1) : body).replace(/[\\\]^]/g, '\\$&')}]`;
+            i = close;
+        }
         else if (char === '\\' && i + 1 < pattern.length)
             source += pattern[++i].replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
         else

package/dist/cli.js

@@ -272,7 +272,7 @@ program
 program
     .command('control-install <sshTarget>')
     .description('install the control plane on a Docker-capable host over SSH and issue the root credential into a local 0600 file; it listens for mTLS only, so front it with TCP passthrough rather than a terminating proxy')
-    .requiredOption('--public-url <url>', 'credential-free https origin clients use, including the published port')
+    .requiredOption('--advertise-url <url>', 'credential-free https origin clients use, including the published port')
     .option('--extra-san <name>', 'additional DNS name or IP for the server certificate (repeatable)', collect, [])
     .option('--image <tag>', "Tug image to run (default: ghcr.io/wpelevator/tug:<this CLI's version>)")
     .option('--install-docker', 'install missing Docker Engine and Compose on supported Debian, Ubuntu, Fedora and RHEL-compatible hosts (root required)')
@@ -282,7 +282,7 @@ program
     .option('--recover-root', "replace root's key from the control host without the API (lost credential); other admins are unaffected")
     .option('--mesh', 'enable the WireGuard mesh on control (TUG_MESH=true); install nodes with --mesh too')
     .action(async (sshTarget, o) => {
-    const publicUrl = normalizeControlUrl(o.publicUrl);
+    const advertiseUrl = normalizeControlUrl(o.advertiseUrl);
     if (o.installDocker)
         await bootstrapDocker(sshTarget, true);
     preflightRemote(sshTarget, { ports: [Number(o.port)], minDiskMb: 2048, compose: true });
@@ -292,7 +292,7 @@ program
     const yamlValue = (value) => JSON.stringify(value);
     const compose = await loadTemplate(templatesDir, 'control-compose.yml', {
         IMAGE: yamlValue(image),
-        PUBLIC_URL: yamlValue(new URL(publicUrl).origin),
+        ADVERTISE_URL: yamlValue(new URL(advertiseUrl).origin),
         EXTRA_SANS: yamlValue(o.extraSan.join(',')),
         PORT: o.port,
         MESH: yamlValue(o.mesh ? 'true' : 'false'),
@@ -316,7 +316,7 @@ program
         await writeFileDurable(o.credentialOut, `${String(out.stdout).trim()}\n`, 0o600);
         console.error(`root credential written to ${o.credentialOut}; import it with: tug init ${o.credentialOut}`);
     }
-    console.log(JSON.stringify({ ok: true, sshTarget, url: publicUrl }, null, 2));
+    console.log(JSON.stringify({ ok: true, sshTarget, url: advertiseUrl }, null, 2));
 });
 const AGENT_STATE = '/var/lib/tug';
 function addNodeIdentityOptions(command) {
@@ -730,6 +730,7 @@ async function makeContext() {
         await createSourceArchive(process.cwd(), tmp, [
             resolvedConfig.file,
             resolvedConfig.localFile,
+            ...(resolvedConfig.credentialFile ? [resolvedConfig.credentialFile] : []),
         ]);
     }
     catch (error) {

package/dist/compose.d.ts

@@ -36,6 +36,8 @@ export declare function isRolling(svc: ComposeService | undefined): boolean;
 export declare const SUPPORTED_SERVICE_KEYS: readonly string[];
 /** Lower-cased ingress hostnames a Compose definition claims, by `service` name. */
 export declare function ingressHostsOf(compose: ComposeFile): Map<string, string>;
+/** True when two lowercase ingress hosts could route the same request: equal, or one is a `*.` wildcard covering the other. */
+export declare function ingressHostsOverlap(a: string, b: string): boolean;
 export declare function validateCompose(compose: ComposeFile | undefined, nodes?: string[]): asserts compose is ComposeFile;
 export interface BuildDesiredStateOptions {
     project: string;

package/dist/compose.js

@@ -289,6 +289,15 @@ export function ingressHostsOf(compose) {
     }
     return hosts;
 }
+/** True when two lowercase ingress hosts could route the same request: equal, or one is a `*.` wildcard covering the other. */
+export function ingressHostsOverlap(a, b) {
+    if (a === b)
+        return true;
+    const suffix = (host) => (host.startsWith('*.') ? host.slice(1) : undefined);
+    const wa = suffix(a);
+    const wb = suffix(b);
+    return (wa !== undefined && b.endsWith(wa)) || (wb !== undefined && a.endsWith(wb));
+}
 export function validateCompose(compose, nodes = []) {
     if (!compose?.services || typeof compose.services !== 'object')
         throw new Error('compose file must define services');

package/dist/control-credential.js

@@ -25,15 +25,15 @@ export function parseIssueArgs(argv) {
  */
 export async function issueHostCredential(args) {
     const dataDir = process.env.TUG_DATA_DIR || './data';
-    const publicUrl = process.env.TUG_PUBLIC_URL;
-    if (!publicUrl)
-        throw new Error('TUG_PUBLIC_URL is required');
+    const advertiseUrl = process.env.TUG_ADVERTISE_URL;
+    if (!advertiseUrl)
+        throw new Error('TUG_ADVERTISE_URL is required');
     const db = await openDb(path.join(dataDir, 'tug.db'));
     try {
         const fresh = !db.get('SELECT 1 FROM operator_credentials') && !db.get('SELECT 1 FROM nodes');
         const pki = await Pki.load(path.join(dataDir, 'pki'), fresh);
         const request = parseCredentialRequest({ name: args.name, role: args.role });
-        const created = await createCredential(db, pki, new URL(publicUrl).origin, request, 'host', {
+        const created = await createCredential(db, pki, new URL(advertiseUrl).origin, request, 'host', {
             replace: args.replace,
         });
         if (args.replace)

package/dist/control.d.ts

@@ -27,7 +27,7 @@ export declare function createApp(options?: {
     openDatabase?: typeof openDb;
     /** Minimum time between event prunes triggered by agent reports; default one hour. */ eventPruneIntervalMs?: number;
     /** Override the live open/agent startup timeout in milliseconds. */ liveStartTimeoutMs?: number;
-    /** Credential-free HTTPS origin clients use to reach control; defaults to `TUG_PUBLIC_URL`. */ publicUrl?: string;
+    /** Credential-free HTTPS origin clients use to reach control; defaults to `TUG_ADVERTISE_URL`. */ advertiseUrl?: string;
     /**
      * Replaces certificate-based identity resolution. Only for in-process tests that skip TLS; production never sets it.
      * It returns the principal URI and key hash a connection would have presented.

package/dist/control.js

@@ -16,14 +16,14 @@ import * as tar from 'tar';
 import { openDb, openSnapshotDb } from "./db.js";
 import { isUniqueViolation } from "./db-driver.js";
 import { encrypt, decrypt, loadOrCreateMasterKey } from "./secrets.js";
-import { buildDesiredState, ingressHostsOf, loopbackIngressServices, serviceSecretNames, validateCompose, } from "./compose.js";
+import { buildDesiredState, ingressHostsOf, ingressHostsOverlap, loopbackIngressServices, serviceSecretNames, validateCompose, } from "./compose.js";
 import { buildImage, unpackContext, run as runCommand } from "./build.js";
 import { sentinelNames } from "./normalize.js";
 import { ensureDir, errMessage, id, now } from "./util.js";
 import { ENROLL_DEFAULT_TTL_MS, NODE_LIFETIME_MS, Pki, SERVER_LIFETIME_MS, encodeCredential, identityUri, namesKey, parseIdentityUri, peerIdentity, serverNames, writeFileDurable, } from "./pki.js";
 import { EXPIRY_WARN_DAYS, certificateExpiry, diagnoseNode } from "./diagnostics.js";
 import { serverTlsOptions } from "./tls-server.js";
-import { DEFAULT_MESH_CIDR, DEFAULT_WG_PORT, WG_INTERFACE, WG_KEEPALIVE, allocateOverlayIp, isWgKey, parseCidr, wgEndpoint, } from "./mesh.js";
+import { DEFAULT_MESH_CIDR, DEFAULT_WG_PORT, WG_INTERFACE, WG_KEEPALIVE, allocateOverlayIp, isWgKey, parseCidr, wgEndpoint, isNodeEndpoint, isNodeHost, } from "./mesh.js";
 import { buildIngressWork, resolveServiceEndpoints } from "./ingress.js";
 import { parseStatusReport } from "./status-report.js";
 import { ACTIVE_DEPLOYMENT_STATES, LIVE_MAX_FRAME_BYTES, LIVE_MAX_BUFFERED_BYTES, LIVE_MAX_SESSIONS, LIVE_START_TIMEOUT_MS, BACKUP_COMMAND_TYPES, } from "./protocol.js";
@@ -479,10 +479,10 @@ export async function createApp(options = {}) {
     const masterKey = await loadOrCreateMasterKey(masterKeyFile);
     // A CA is created only for a fresh installation; existing state with missing or mismatched CA material is a startup error.
     const pki = await Pki.load(path.join(DATA_DIR, 'pki'), !db.get('SELECT 1 FROM operator_credentials') && !db.get('SELECT 1 FROM nodes'));
-    const publicUrl = () => {
-        const url = options.publicUrl ?? process.env.TUG_PUBLIC_URL;
+    const advertiseUrl = () => {
+        const url = options.advertiseUrl ?? process.env.TUG_ADVERTISE_URL;
         if (!url)
-            throw httpError(500, 'TUG_PUBLIC_URL is not set');
+            throw httpError(500, 'TUG_ADVERTISE_URL is not set');
         return new URL(url).origin;
     };
     const app = express();
@@ -708,11 +708,10 @@ export async function createApp(options = {}) {
         for (const other of currentDesiredStates()) {
             if (other.project === project)
                 continue;
-            for (const [host, service] of ingressHostsOf(other.compose)) {
-                const mine = wanted.get(host);
-                if (mine)
-                    throw httpError(409, `${mine}: ingress.host ${host} is already routed by project ${other.project} (${service})`);
-            }
+            for (const [host, service] of ingressHostsOf(other.compose))
+                for (const [wantedHost, mine] of wanted)
+                    if (ingressHostsOverlap(wantedHost, host))
+                        throw httpError(409, `${mine}: ingress.host ${wantedHost} ${wantedHost === host ? 'is' : `overlaps ${host},`} already routed by project ${other.project} (${service})`);
         }
     }
     function createRollback(project, opts) {
@@ -995,6 +994,10 @@ export async function createApp(options = {}) {
     function insertNode(input) {
         if (!NODE_NAME.test(input.name))
             throw httpError(400, 'node name must be 1-63 letters, numbers, dots, underscores or hyphens');
+        if (input.address && !isNodeHost(input.address))
+            throw httpError(400, 'address must be an IP address or hostname without a port');
+        if (input.publicAddress && !isNodeEndpoint(input.publicAddress))
+            throw httpError(400, 'publicAddress must be an IP address or hostname with an optional port');
         if (input.wgPublicKey !== undefined && !isWgKey(input.wgPublicKey))
             throw httpError(400, 'wgPublicKey must be a base64 WireGuard public key');
         const ts = now();
@@ -1008,7 +1011,7 @@ export async function createApp(options = {}) {
         node: nodeInfo(nodeId),
         certificate: cert,
         ca: pki.caPem,
-        url: publicUrl(),
+        url: advertiseUrl(),
     });
     // The node generates its key and CSR; an admin posts the CSR here. The private key is never transmitted.
     api('post', '/api/v1/nodes/:name/identity', null, async (req, res) => {
@@ -1079,7 +1082,7 @@ export async function createApp(options = {}) {
             return res.status(400).json({ error: 'labels must be a list of strings' });
         const ttlSeconds = Math.max(1, Number(req.body.ttlSeconds ?? ENROLL_DEFAULT_TTL_MS / 1000));
         const rowId = id('enr');
-        const issued = await pki.issueClient(identityUri('enroll', rowId), ttlSeconds * 1000, publicUrl());
+        const issued = await pki.issueClient(identityUri('enroll', rowId), ttlSeconds * 1000, advertiseUrl());
         const expiresAt = issued.notAfter.toISOString();
         db.run('DELETE FROM enrollment_credentials WHERE expires_at < ?', new Date(Date.now() - 86_400_000).toISOString());
         // Minting again for a name revokes its previous unconsumed key.
@@ -1267,7 +1270,7 @@ export async function createApp(options = {}) {
     });
     api('post', '/api/v1/credentials', null, async (req, res) => {
         const request = parseCredentialRequest(req.body);
-        const created = await createCredential(db, pki, publicUrl(), request, req.actor.name);
+        const created = await createCredential(db, pki, advertiseUrl(), request, req.actor.name);
         audit(req.actor, {
             type: 'credential.create',
             message: `credential ${created.name} (${created.role}${created.projects ? `, projects: ${created.projects.join(', ')}` : ''}) created by ${req.actor.name}`,
@@ -1624,6 +1627,10 @@ export async function createApp(options = {}) {
                 }
             }
             const nodes = nodeRows.map((row) => ({ name: row.name }));
+            for (const [name, svc] of Object.entries(compose.services || {}))
+                for (const node of svc['x-tug']?.placement?.nodes || [])
+                    if (!nodes.some((n) => n.name === node))
+                        throw httpError(400, `${name}: placement node ${node} is not an enabled node`);
             try {
                 validateCompose(compose, nodes.map((n) => n.name));
             }
@@ -2460,6 +2467,14 @@ export async function createApp(options = {}) {
             return res.status(409).json({ error: `command is ${command.state}, not running` });
         if (!command.project_id || !backupDestination())
             return res.status(409).json({ error: 'no backup destination is configured' });
+        // A command that outlived the project's placement on this node (a newer version moved it) gets nothing.
+        const desiredRow = currentDesired(command.project_id);
+        const desiredNow = desiredRow
+            ? JSON.parse(desiredRow.state_json)
+            : undefined;
+        const placedHere = Object.values(desiredNow?.services || {}).some((svc) => svc.placement?.nodes?.includes(req.node.name));
+        if (!placedHere)
+            return res.status(403).json({ error: 'project is no longer placed on this node' });
         const response = {
             env: {
                 ...backupEnv(),
@@ -2583,18 +2598,18 @@ async function ensureServerCredential(pki, dir, names, force = false) {
 export async function listen(app, port = PORT) {
     const pki = app.locals.pki;
     const dataDir = app.locals.dataDir;
-    const publicUrl = process.env.TUG_PUBLIC_URL;
-    if (!publicUrl)
-        throw new Error('TUG_PUBLIC_URL is required: the credential-free https origin clients connect to');
-    const url = new URL(publicUrl);
+    const advertiseUrl = process.env.TUG_ADVERTISE_URL;
+    if (!advertiseUrl)
+        throw new Error('TUG_ADVERTISE_URL is required: the credential-free https origin clients connect to');
+    const url = new URL(advertiseUrl);
     if (url.protocol !== 'https:' ||
         url.username ||
         url.password ||
         url.search ||
         url.hash ||
         url.pathname !== '/')
-        throw new Error('TUG_PUBLIC_URL must be a credential-free https origin such as https://control.example.com:8443');
-    const names = serverNames(publicUrl, (process.env.TUG_EXTRA_SANS || '').split(','));
+        throw new Error('TUG_ADVERTISE_URL must be a credential-free https origin such as https://control.example.com:8443');
+    const names = serverNames(advertiseUrl, (process.env.TUG_EXTRA_SANS || '').split(','));
     const credential = await ensureServerCredential(pki, dataDir, names);
     const server = https.createServer(serverTlsOptions({ cert: credential.cert, key: credential.key, ca: pki.caPem }), app);
     server.requestTimeout = 5 * 60_000;

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_ADVERTISE_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/mesh.d.ts

@@ -34,6 +34,10 @@ export declare function parseCidr(cidr: string): {
 };
 /** First free host address in the mesh CIDR (never the network or broadcast address). */
 export declare function allocateOverlayIp(cidr: string, used: Iterable<string>): string;
+/** 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;
+/** A node host with an optional port: `host`, `host:port` or `[ipv6]:port`. */
+export declare const isNodeEndpoint: (value: unknown) => value is 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). */

package/dist/mesh.js

@@ -2,6 +2,7 @@
 // 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 { isIP } from 'node:net';
 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. */
@@ -96,6 +97,22 @@ export function allocateOverlayIp(cidr, used) {
     }
     throw new Error(`mesh CIDR ${cidr} has no free overlay addresses`);
 }
+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)));
+/** A node host with an optional port: `host`, `host:port` or `[ipv6]:port`. */
+export const isNodeEndpoint = (value) => {
+    if (typeof value !== 'string')
+        return false;
+    const bracketed = /^\[([^\]]+)\](?::(\d{1,5}))?$/.exec(value);
+    const parts = bracketed ?? (isIP(value) ? null : /^([^:]+)(?::(\d{1,5}))?$/.exec(value));
+    const [host, port] = parts ? [parts[1], parts[2]] : [value, undefined];
+    if (bracketed ? isIP(host) !== 6 : !isNodeHost(host))
+        return false;
+    return port === undefined || (Number(port) >= 1 && Number(port) <= 65535);
+};
 /** `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();

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(advertiseUrl: 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(advertiseUrl, extras = []) {
     const names = { dns: [], ip: [] };
-    const host = new URL(publicUrl).hostname.replace(/^\[|\]$/g, '');
+    const host = new URL(advertiseUrl).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/templates/control-compose.yml

@@ -6,7 +6,7 @@ services:
     environment:
       PORT: 8443
       TUG_DATA_DIR: /data
-      TUG_PUBLIC_URL: {{PUBLIC_URL}}
+      TUG_ADVERTISE_URL: {{ADVERTISE_URL}}
       TUG_EXTRA_SANS: {{EXTRA_SANS}}
       TUG_MESH: {{MESH}}
     ports:

package/package.json

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