@wpelevator/tug 0.0.0 → 0.2.0

package/dist/archive.js

@@ -0,0 +1,20 @@
+import { createReadStream } from 'node:fs';
+import * as tar from 'tar';
+export async function scanArchive(file, inspect) {
+    await new Promise((resolve, reject) => {
+        const input = createReadStream(file);
+        const parser = new tar.Parser({ strict: true, onReadEntry(entry) {
+                try {
+                    inspect(entry);
+                    entry.resume();
+                }
+                catch (error) {
+                    parser.abort(error);
+                }
+            } });
+        input.once('error', reject);
+        parser.once('error', error => { input.destroy(); reject(error); });
+        parser.once('end', resolve);
+        input.pipe(parser);
+    });
+}

package/dist/artifacts.d.ts

@@ -0,0 +1,23 @@
+import { Transform } from 'node:stream';
+import type { RunResult } from './build.ts';
+export type ImageRunner = (cmd: string, args: string[]) => Promise<RunResult>;
+export interface ImageInfo {
+    imageId: string;
+    platform: string;
+}
+export interface ArchiveInfo extends ImageInfo {
+    sha256: string;
+    sizeBytes: number;
+}
+export declare function inspectImage(imageRef: string, runner?: ImageRunner): Promise<ImageInfo>;
+export declare function hashArchive(file: string): Promise<{
+    sha256: string;
+    sizeBytes: number;
+}>;
+export declare function saveImageArchive(imageRef: string, file: string): Promise<ArchiveInfo>;
+/** Validate Docker save metadata before Docker can import attacker-selected repository tags. */
+export declare function validateImageArchive(file: string, expectedRef: string, maxExpandedBytes?: number, requireManagedReference?: boolean): Promise<ArchiveInfo>;
+export declare function verifyDownload(expected: {
+    sha256: string;
+    sizeBytes: number;
+}): Transform;

package/dist/artifacts.js

@@ -0,0 +1,238 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createGzip } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+import { Transform } from 'node:stream';
+import { run } from "./build.js";
+import { scanArchive } from "./archive.js";
+export async function inspectImage(imageRef, runner = run) {
+    const images = JSON.parse((await runner('docker', ['image', 'inspect', imageRef])).out);
+    const image = images[0];
+    if (!/^sha256:[a-f0-9]{64}$/.test(image?.Id) || !image.Os || !image.Architecture)
+        throw new Error(`invalid Docker image metadata for ${imageRef}`);
+    return { imageId: image.Id, platform: `${image.Os}/${image.Architecture}` };
+}
+export async function hashArchive(file) {
+    const hash = createHash('sha256');
+    let sizeBytes = 0;
+    for await (const chunk of createReadStream(file)) {
+        hash.update(chunk);
+        sizeBytes += chunk.length;
+    }
+    return { sha256: hash.digest('hex'), sizeBytes };
+}
+export async function saveImageArchive(imageRef, file) {
+    const child = spawn('docker', ['save', imageRef], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let error = '';
+    child.stderr.on('data', chunk => { error = (error + chunk).slice(-4000); });
+    const finished = new Promise((resolve, reject) => { child.once('error', reject); child.once('close', code => code === 0 ? resolve() : reject(new Error(`docker save failed (${code}): ${error}`))); });
+    try {
+        await Promise.all([pipeline(child.stdout, createGzip(), createWriteStream(file, { mode: 0o600 })), finished]);
+    }
+    catch (e) {
+        child.kill();
+        await fs.rm(file, { force: true });
+        throw e;
+    }
+    return validateImageArchive(file, imageRef, 20 * 1024 ** 3, false);
+}
+/** Validate Docker save metadata before Docker can import attacker-selected repository tags. */
+export async function validateImageArchive(file, expectedRef, maxExpandedBytes = 20 * 1024 ** 3, requireManagedReference = true) {
+    if (requireManagedReference && !/^tug-build\/[a-z0-9._/-]+:[a-zA-Z0-9._-]+$/.test(expectedRef))
+        throw new Error('local image reference must be a unique tug-build/ reference');
+    const names = new Set();
+    const regular = new Set();
+    let expanded = 0;
+    let entries = 0;
+    let invalid;
+    const blobMetadata = new Map();
+    const blobHashes = new Map();
+    let metadataBytes = 0;
+    let manifestBytes;
+    let indexBytes;
+    let repositoriesBytes;
+    await scanArchive(file, entry => {
+        const name = entry.path.replace(/^\.\//, '');
+        if (++entries > 100000 || (expanded += entry.size) > maxExpandedBytes)
+            invalid = 'image archive exceeds expanded limits';
+        if (name.startsWith('/') || name.split('/').includes('..') || !['File', 'Directory'].includes(entry.type) || names.has(name))
+            invalid = 'unsafe image archive entry';
+        if (invalid)
+            throw new Error(invalid);
+        names.add(name);
+        if (entry.type === 'File')
+            regular.add(name);
+        if (/^blobs\/sha256\/[a-f0-9]{64}$/.test(name)) {
+            const hash = createHash('sha256');
+            const chunks = [];
+            let json = false;
+            let first = true;
+            entry.on('data', (chunk) => {
+                hash.update(chunk);
+                if (first) {
+                    json = entry.size <= 4 * 1024 ** 2 && (chunk[0] === 123 || chunk[0] === 91);
+                    first = false;
+                }
+                if (json) {
+                    metadataBytes += chunk.length;
+                    if (metadataBytes > 16 * 1024 ** 2) {
+                        invalid = 'OCI metadata exceeds limit';
+                        json = false;
+                        chunks.length = 0;
+                    }
+                    else
+                        chunks.push(Buffer.from(chunk));
+                }
+            });
+            entry.on('end', () => { blobHashes.set(name, hash.digest('hex')); if (json)
+                blobMetadata.set(name, Buffer.concat(chunks)); });
+        }
+        if (['manifest.json', 'index.json', 'repositories'].includes(name) && !invalid) {
+            if (entry.size > 1024 ** 2) {
+                throw new Error('image manifest exceeds limit');
+            }
+            const chunks = [];
+            entry.on('data', chunk => chunks.push(Buffer.from(chunk)));
+            entry.on('end', () => { const value = Buffer.concat(chunks); if (name === 'manifest.json')
+                manifestBytes = value;
+            else if (name === 'index.json')
+                indexBytes = value;
+            else
+                repositoriesBytes = value; });
+        }
+    });
+    if (invalid)
+        throw new Error(invalid);
+    const manifest = JSON.parse(manifestBytes?.toString() || 'null');
+    if (!Array.isArray(manifest) || manifest.length !== 1 || JSON.stringify(manifest[0].RepoTags) !== JSON.stringify([expectedRef]))
+        throw new Error('archive must contain exactly the declared Tug image tag');
+    if (typeof manifest[0].Config !== 'string' || !regular.has(manifest[0].Config))
+        throw new Error('image archive is missing its configuration');
+    if (!Array.isArray(manifest[0].Layers) || manifest[0].Layers.some((layer) => typeof layer !== 'string' || !regular.has(layer)))
+        throw new Error('image archive is missing layers');
+    let configBytes;
+    await scanArchive(file, entry => {
+        if (entry.path.replace(/^\.\//, '') !== manifest[0].Config)
+            return;
+        if (entry.size > 4 * 1024 ** 2) {
+            throw new Error('image configuration exceeds limit');
+        }
+        const chunks = [];
+        entry.on('data', chunk => chunks.push(Buffer.from(chunk)));
+        entry.on('end', () => { configBytes = Buffer.concat(chunks); });
+    });
+    if (invalid)
+        throw new Error(invalid);
+    if (!configBytes)
+        throw new Error('image archive is missing its configuration');
+    if (indexBytes) {
+        const index = JSON.parse(indexBytes.toString());
+        const descriptor = index.manifests?.[0];
+        const annotations = descriptor?.annotations || {};
+        const allowedNames = new Set([expectedRef, `docker.io/${expectedRef}`, ...(!expectedRef.includes('/') ? [`docker.io/library/${expectedRef}`] : [])]);
+        if (!Array.isArray(index.manifests) || index.manifests.length < 1 || !allowedNames.has(annotations['io.containerd.image.name']) || (annotations['org.opencontainers.image.ref.name'] && !allowedNames.has(annotations['org.opencontainers.image.ref.name']) && annotations['org.opencontainers.image.ref.name'] !== expectedRef.split(':').at(-1)))
+            throw new Error('OCI index contains unexpected image names');
+        const expectedConfig = `sha256:${createHash('sha256').update(configBytes).digest('hex')}`;
+        const expectedLayers = manifest[0].Layers;
+        const visited = new Set();
+        let runnable = 0;
+        const readBlob = (digest) => {
+            if (!/^sha256:[a-f0-9]{64}$/.test(digest))
+                throw new Error('invalid OCI content digest');
+            const name = `blobs/sha256/${digest.slice(7)}`;
+            const bytes = blobMetadata.get(name);
+            if (!bytes || blobHashes.get(name) !== digest.slice(7))
+                throw new Error('OCI metadata content digest mismatch or missing blob');
+            return JSON.parse(bytes.toString());
+        };
+        const isAttestationDocument = (document, imageConfig) => (Object.keys(imageConfig).length === 0 && document.artifactType === 'application/vnd.docker.attestation.manifest.v1+json') || (imageConfig.os === 'unknown' && imageConfig.architecture === 'unknown');
+        /** An attestation is acceptable only when it describes this exact saved image and carries nothing but in-toto statements. */
+        const verifyAttestation = (document, subject) => {
+            const subjectConfig = subject ? readBlob(subject).config : undefined;
+            if (subjectConfig?.digest !== expectedConfig)
+                throw new Error('attestation subject does not match saved image');
+            for (const layer of document.layers) {
+                const name = `blobs/sha256/${layer.digest?.slice(7)}`;
+                if (layer.mediaType !== 'application/vnd.in-toto+json' || !/^sha256:[a-f0-9]{64}$/.test(layer.digest) || blobHashes.get(name) !== layer.digest.slice(7))
+                    throw new Error('invalid attestation layer');
+            }
+        };
+        const walk = (desc) => {
+            if (visited.has(desc.digest))
+                return;
+            visited.add(desc.digest);
+            if (desc.annotations?.['io.containerd.image.name'] || desc.annotations?.['org.opencontainers.image.ref.name'])
+                throw new Error('nested OCI metadata contains unexpected image names');
+            const document = readBlob(desc.digest);
+            if (Array.isArray(document.manifests)) {
+                for (const child of document.manifests) {
+                    if (typeof child.digest !== 'string')
+                        throw new Error('invalid OCI descriptor');
+                    if (regular.has(`blobs/sha256/${child.digest.slice(7)}`))
+                        walk(child);
+                }
+                return;
+            }
+            const configDescriptor = document.config;
+            if (!configDescriptor?.digest || !Array.isArray(document.layers))
+                throw new Error('invalid OCI image manifest');
+            const imageConfig = readBlob(configDescriptor.digest);
+            const attestation = desc.annotations?.['vnd.docker.reference.type'] === 'attestation-manifest' && desc.platform?.os === 'unknown' && desc.platform?.architecture === 'unknown';
+            if (attestation && isAttestationDocument(document, imageConfig)) {
+                verifyAttestation(document, document.subject?.digest || desc.annotations?.['vnd.docker.reference.digest']);
+                return;
+            }
+            if (configDescriptor.digest !== expectedConfig)
+                throw new Error('OCI graph configuration does not match saved image');
+            const layerPaths = document.layers.map(layer => {
+                if (!/^sha256:[a-f0-9]{64}$/.test(layer.digest))
+                    throw new Error('invalid OCI layer digest');
+                const name = `blobs/sha256/${layer.digest.slice(7)}`;
+                if (!regular.has(name) || blobHashes.get(name) !== layer.digest.slice(7))
+                    throw new Error('OCI layer content digest mismatch');
+                return name;
+            });
+            if (JSON.stringify(layerPaths) !== JSON.stringify(expectedLayers))
+                throw new Error('OCI graph layers do not match saved image');
+            runnable++;
+        };
+        walk({ ...descriptor, annotations: {} });
+        if (runnable !== 1)
+            throw new Error('OCI archive must contain exactly one runnable saved image');
+        // On a containerd image store, `docker save` also lists build attestations that refer to the image as extra
+        // top-level entries. They carry no image name, so they cannot create tags; accept them only when they are
+        // genuine attestations of this exact image and reject any other extra manifest.
+        for (const extra of index.manifests.slice(1)) {
+            const annotationNames = Object.keys(extra.annotations || {});
+            const unexpected = () => new Error('OCI index contains an unexpected extra manifest');
+            if (annotationNames.length !== 1 || annotationNames[0] !== 'io.containerd.manifest.subject' || !/^sha256:[a-f0-9]{64}$/.test(extra.digest))
+                throw unexpected();
+            const document = readBlob(extra.digest);
+            const configDescriptor = document.config;
+            const subject = document.subject?.digest;
+            if (!configDescriptor?.digest || !Array.isArray(document.layers) || subject !== extra.annotations['io.containerd.manifest.subject'] || !isAttestationDocument(document, readBlob(configDescriptor.digest)))
+                throw unexpected();
+            verifyAttestation(document, subject);
+        }
+    }
+    if (repositoriesBytes) {
+        const repositories = JSON.parse(repositoriesBytes.toString());
+        const colon = expectedRef.lastIndexOf(':');
+        const repo = expectedRef.slice(0, colon);
+        const tag = expectedRef.slice(colon + 1);
+        if (JSON.stringify(Object.keys(repositories)) !== JSON.stringify([repo]) || JSON.stringify(Object.keys(repositories[repo])) !== JSON.stringify([tag]))
+            throw new Error('archive repositories contain unexpected image tags');
+    }
+    const config = JSON.parse(configBytes.toString());
+    if (config.os !== 'linux' || !['amd64', 'arm64'].includes(config.architecture))
+        throw new Error('only linux/amd64 and linux/arm64 image archives are supported');
+    return { imageId: `sha256:${createHash('sha256').update(configBytes).digest('hex')}`, platform: `${config.os}/${config.architecture}`, ...await hashArchive(file) };
+}
+export function verifyDownload(expected) {
+    const hash = createHash('sha256');
+    let bytes = 0;
+    return new Transform({ transform(chunk, _encoding, callback) { bytes += chunk.length; if (bytes > expected.sizeBytes)
+            return callback(new Error('image download exceeds expected size')); hash.update(chunk); callback(null, chunk); }, flush(callback) { callback(bytes === expected.sizeBytes && hash.digest('hex') === expected.sha256 ? undefined : new Error('image download checksum or size mismatch')); } });
+}

package/dist/build.d.ts

@@ -0,0 +1,22 @@
+export interface RunResult {
+    out: string;
+    err: string;
+}
+export interface RunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface BuildSpec {
+    context?: string;
+    dockerfile?: string;
+}
+export declare function run(cmd: string, args: string[], opts?: RunOptions): Promise<RunResult>;
+export declare function unpackContext(tarball: string, dest: string): Promise<void>;
+export interface BuildAndPushOptions {
+    contextDir: string;
+    service: string;
+    buildSpec: string | BuildSpec;
+    imageRef: string;
+    push?: boolean;
+}
+export declare function buildAndPush({ contextDir, service, buildSpec, imageRef, push }: BuildAndPushOptions): Promise<void>;

package/dist/build.js

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import * as tar from 'tar';
+import { scanArchive } from "./archive.js";
+import { ensureDir, exists } from "./util.js";
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(cmd, args, { ...opts, 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}`)));
+    });
+}
+export async function unpackContext(tarball, dest) {
+    await fs.rm(dest, { recursive: true, force: true });
+    await ensureDir(dest);
+    let expanded = 0;
+    let entries = 0;
+    await scanArchive(tarball, entry => {
+        expanded += entry.size;
+        entries++;
+        if (expanded > 20 * 1024 ** 3 || entries > 100000 || path.isAbsolute(entry.path) || entry.path.split('/').includes('..') || !['File', 'Directory'].includes(entry.type))
+            throw new Error('source context has unsafe entries or exceeds expanded limits');
+    });
+    await tar.x({ file: tarball, cwd: dest, strict: true });
+}
+export async function buildAndPush({ contextDir, service, buildSpec, imageRef, push = true }) {
+    const buildPath = typeof buildSpec === 'string' ? buildSpec : buildSpec?.context || '.';
+    const dockerfilePath = typeof buildSpec === 'object' && buildSpec.dockerfile ? path.resolve(contextDir, buildPath, buildSpec.dockerfile) : undefined;
+    if (dockerfilePath && !dockerfilePath.startsWith(`${path.resolve(contextDir)}${path.sep}`))
+        throw new Error(`Dockerfile escapes uploaded root for ${service}`);
+    const dockerfile = dockerfilePath ? ['-f', dockerfilePath] : [];
+    const fullContext = path.resolve(contextDir, buildPath);
+    if (fullContext !== path.resolve(contextDir) && !fullContext.startsWith(`${path.resolve(contextDir)}${path.sep}`))
+        throw new Error(`build context escapes uploaded root for ${service}`);
+    if (!(await exists(fullContext)))
+        throw new Error(`build context not found for ${service}: ${buildPath}`);
+    await run('docker', ['build', ...dockerfile, '-t', imageRef, fullContext]);
+    if (push)
+        await run('docker', ['push', imageRef]);
+}

package/dist/cli-build.d.ts

@@ -0,0 +1,15 @@
+import { buildAndPush } from './build.ts';
+import { saveImageArchive } from './artifacts.ts';
+import type { ComposeFile, LocalImageUpload } from './protocol.ts';
+export interface LocalBuildDependencies {
+    build: typeof buildAndPush;
+    save: typeof saveImageArchive;
+    nonce: () => string;
+    remove: (imageRef: string) => Promise<void>;
+    cleanupWarning?: (message: string) => void;
+}
+/** Credential exclusions are mandatory and cannot be re-included by source ignore rules. */
+export declare function sourceArchiveFilter(entry: string, configPaths: string[], ignores: string[]): boolean;
+export declare function createSourceArchive(contextDir: string, archive: string, configFiles: string[]): Promise<void>;
+/** Build only application build services; callers own temporary files and upload transport. */
+export declare function prepareLocalImages(compose: ComposeFile, contextDir: string, directory: string, dependencies?: LocalBuildDependencies): Promise<LocalImageUpload[]>;

package/dist/cli-build.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import * as tar from 'tar';
+import { buildAndPush, run } from "./build.js";
+import { saveImageArchive } from "./artifacts.js";
+/** Credential exclusions are mandatory and cannot be re-included by source ignore rules. */
+export function sourceArchiveFilter(entry, configPaths, ignores) {
+    const relative = entry.replaceAll('\\', '/').replace(/^(\.\/)+/, '').replace(/\/$/, '');
+    if (relative.split('/').some(part => ['.git', '.tug.json'].includes(part)))
+        return false;
+    return ![...configPaths, ...ignores].some(ignore => relative === ignore || relative.startsWith(`${ignore}/`));
+}
+export async function createSourceArchive(contextDir, archive, configFiles) {
+    const configPaths = configFiles.map(file => path.relative(contextDir, file).split(path.sep).join('/')).filter(file => file !== '..' && !file.startsWith('../') && !path.isAbsolute(file));
+    const ignores = ['node_modules', 'data', 'registry-data'];
+    try {
+        ignores.push(...(await fs.readFile(path.join(contextDir, '.dockerignore'), 'utf8')).split(/\r?\n/).map(line => line.trim().replace(/\/$/, '')).filter(line => line && !line.startsWith('#') && !line.startsWith('!')));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await tar.c({ gzip: true, file: archive, cwd: contextDir, filter: entry => sourceArchiveFilter(entry, configPaths, ignores) }, ['.']);
+}
+/** Build only application build services; callers own temporary files and upload transport. */
+export async function prepareLocalImages(compose, contextDir, directory, dependencies = { build: buildAndPush, save: saveImageArchive, nonce: randomUUID, remove: async (imageRef) => { await run('docker', ['image', 'rm', imageRef]); } }) {
+    const images = [];
+    const nonce = dependencies.nonce();
+    for (const [service, spec] of Object.entries(compose.services)) {
+        if (!spec.build)
+            continue;
+        const field = `image-${images.length}`;
+        const imageRef = `tug-build/${nonce}/${field}:local`;
+        try {
+            await dependencies.build({ contextDir, service, buildSpec: spec.build, imageRef, push: false });
+            const archive = await dependencies.save(imageRef, path.join(directory, `${field}.tar.gz`));
+            images.push({ service, imageRef, ...archive, field });
+        }
+        finally {
+            try {
+                await dependencies.remove(imageRef);
+            }
+            catch (error) {
+                (dependencies.cleanupWarning || console.warn)(`Could not remove temporary application image ${imageRef}: ${error.message}`);
+            }
+        }
+    }
+    return images;
+}

package/dist/cli-config.d.ts

@@ -0,0 +1,20 @@
+export interface CliConfig {
+    controlUrl?: string;
+    operatorToken?: string;
+    project?: string;
+}
+export interface ConnectionOptions {
+    config?: string;
+    controlUrl?: string;
+    project?: string;
+}
+export interface ResolvedCliConfig {
+    file: string;
+    controlUrl: string;
+    operatorToken?: string;
+    project: string;
+}
+/** Resolve adapter settings once; domain operations receive these explicit values. */
+export declare function resolveCliConfig(options: ConnectionOptions, env: NodeJS.ProcessEnv, cwd: string, creating?: boolean): Promise<ResolvedCliConfig>;
+export declare function normalizeControlUrl(value: string): string;
+export declare function integerOption(value: string, name: string, minimum?: number, maximum?: number): number;

package/dist/cli-config.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** Resolve adapter settings once; domain operations receive these explicit values. */
+export async function resolveCliConfig(options, env, cwd, creating = false) {
+    for (const key of ['config', 'controlUrl', 'project'])
+        if (options[key] !== undefined && (!options[key].trim() || /[\r\n\0]/.test(options[key])))
+            throw new Error(`--${key.replace(/[A-Z]/g, c => '-' + c.toLowerCase())} must be a nonempty single-line value`);
+    const file = path.resolve(cwd, options.config || env.TUG_CONFIG || '.tug.json');
+    let config = {};
+    try {
+        const input = JSON.parse(await fs.readFile(file, 'utf8'));
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new Error('expected a JSON object');
+        for (const key of ['controlUrl', 'operatorToken', 'project']) {
+            const value = input[key];
+            if (value !== undefined && (typeof value !== 'string' || !value.trim()))
+                throw new Error(`${key} must be a nonempty string`);
+        }
+        config = input;
+    }
+    catch (error) {
+        const missing = error.code === 'ENOENT';
+        if (!missing || (!creating && Boolean(options.config || env.TUG_CONFIG)))
+            throw new Error(`Cannot read config ${file}: ${error.message}`, { cause: error });
+    }
+    const controlUrl = options.controlUrl || env.TUG_CONTROL_URL || config.controlUrl || 'http://localhost:8080';
+    return { file, controlUrl: normalizeControlUrl(controlUrl), operatorToken: env.TUG_TOKEN || config.operatorToken, project: options.project || env.TUG_PROJECT || config.project || 'site' };
+}
+export function normalizeControlUrl(value) {
+    if (!value.trim() || /[\r\n\0]/.test(value))
+        throw new Error('control URL must be a nonempty single-line URL');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('control URL must be an absolute http:// or https:// URL');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+        throw new Error('control URL must use http:// or https:// without credentials, query or fragment');
+    return value.replace(/\/+$/, '');
+}
+export function integerOption(value, name, minimum = 1, maximum = Number.MAX_SAFE_INTEGER) {
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < minimum || Number(value) > maximum)
+        throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`);
+    return Number(value);
+}

package/dist/cli-install.d.ts

@@ -0,0 +1,7 @@
+export declare const MESH_RUN_FLAGS = "--network host --cap-add NET_ADMIN";
+export declare function shellQuote(value: unknown): string;
+export declare function dockerRunSnippet(image: string, joinKey: string, mesh?: boolean): string;
+/** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
+export declare function enrollmentCloudInit(bootstrap: string, command: string): string;
+/** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
+export declare function meshPortCheck(port: number): string;

package/dist/cli-install.js

@@ -0,0 +1,31 @@
+import yaml from 'js-yaml';
+export const MESH_RUN_FLAGS = '--network host --cap-add NET_ADMIN';
+export function shellQuote(value) { return `'${String(value).replace(/'/g, `'\\''`)}'`; }
+export function dockerRunSnippet(image, joinKey, mesh = false) {
+    return `docker run -d --name tug-agent --restart unless-stopped ${mesh ? `${MESH_RUN_FLAGS} -e TUG_MESH=true ` : ''}-v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${shellQuote(image)} agent`;
+}
+/** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
+export function enrollmentCloudInit(bootstrap, command) {
+    return '#cloud-config\n' + yaml.dump({ write_files: [{ path: '/opt/tug/install-docker.sh', permissions: '0700', content: bootstrap }], runcmd: [['sh', '-eu', '-c', `sh /opt/tug/install-docker.sh && ${command}`]] }, { lineWidth: -1, noRefs: true });
+}
+/** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
+export function meshPortCheck(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('mesh port must be an integer from 1 to 65535');
+    return `command -v ss >/dev/null 2>&1 || exit 1
+listeners=$(ss -lun) || exit 1
+if ! printf '%s\\n' "$listeners" | awk '{print $4}' | grep -qE '[.:]${port}$'; then exit 0; fi
+[ "$(docker inspect --format '{{.HostConfig.NetworkMode}}' tug-agent 2>/dev/null)" = host ] || exit 1
+[ "$(docker inspect --format '{{.State.Running}}' tug-agent 2>/dev/null)" = true ] || exit 1
+docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' tug-agent 2>/dev/null | grep -qx 'TUG_MESH=true' || exit 1
+[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/var/lib/tug"}}{{.Source}}{{end}}{{end}}' tug-agent 2>/dev/null)" = /var/lib/tug ] || exit 1
+docker exec tug-agent sh -eu -c ${shellQuote(`
+test -s /var/lib/tug/wireguard/private.key
+test -s /var/lib/tug/wireguard/reported.pub
+test "$(wg show wg0 listen-port)" = "${port}"
+live_key=$(wg show wg0 public-key)
+test -n "$live_key"
+test "$live_key" = "$(wg pubkey < /var/lib/tug/wireguard/private.key)"
+test "$live_key" = "$(cat /var/lib/tug/wireguard/reported.pub)"`)}
+`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};