@wpelevator/tug 0.0.0 → 0.2.0

package/dist/rollout.js

@@ -0,0 +1,319 @@
+// Rolling rollouts on the agent. A service with `x-tug.rollout.strategy: rolling` does not live in the
+// node's main Compose project. Every distinct rendering of it runs as its own Compose project
+// (`<project>-<service>-<hash>`) with a published host port taken from a free range, so the previous
+// revision keeps serving while the new one starts and is health-checked. Control learns the new port
+// from the status report and re-renders the ingress; after a drain delay the previous revision is
+// removed. State lives in `<project dir>/rollout.json` so an agent restart resumes mid-rollout.
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { dumpYaml, isRolling, publishedPort } from "./compose.js";
+import { ensureDir, errMessage, now, parseDuration } from "./util.js";
+export const DEFAULT_DRAIN = '30s';
+export const DEFAULT_PORT_RANGE = '20000-20999';
+const LABEL_PROJECT = 'com.docker.compose.project';
+const LABEL_SERVICE = 'com.docker.compose.service';
+export function parsePortRange(value) {
+    const m = (value || DEFAULT_PORT_RANGE).trim().match(/^(\d+)-(\d+)$/);
+    const lo = Number(m?.[1]);
+    const hi = Number(m?.[2]);
+    if (!m || lo < 1024 || hi > 65535 || lo > hi)
+        throw new Error(`invalid rollout port range ${JSON.stringify(value)} (expected LOW-HIGH within 1024-65535, e.g. ${DEFAULT_PORT_RANGE})`);
+    return [lo, hi];
+}
+/** Compose project names allow lowercase letters, digits, dashes and underscores. */
+export function revisionProject(project, service, hash) {
+    return `${project}-${service}-${hash.slice(0, 8)}`.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+}
+/** Returns `ports` with the host side of its (single) published entry replaced by `port`. */
+export function remapPublishedPort(ports, port) {
+    return ports.map(entry => {
+        if (typeof entry === 'number')
+            return entry;
+        if (typeof entry === 'object')
+            return entry.published !== undefined ? { ...entry, published: port } : entry;
+        const [spec, ...protocol] = String(entry).split('/');
+        const parts = spec.split(':');
+        if (parts.length < 2)
+            return entry;
+        parts[parts.length - 2] = String(port);
+        return [parts.join(':'), ...protocol].join('/');
+    });
+}
+/** Identity of one revision of a service: its rendered definition and the versions of the secrets it uses. */
+export function serviceRevisionHash(desired, rendered, service, secretVersions = {}) {
+    const artifact = desired.services[service]?.artifact;
+    const definition = { ...rendered, image: artifact?.imageId ?? rendered.image };
+    return crypto.createHash('sha256').update(JSON.stringify({ definition, secretVersions })).digest('hex').slice(0, 16);
+}
+/** The Compose file of one rolling revision: the service alone, on the main project's network and volumes. */
+export function rollingCompose(full, project, service, port) {
+    const svc = { ...full.services[service] };
+    delete svc.depends_on;
+    if (port !== null && svc.ports)
+        svc.ports = remapPublishedPort(svc.ports, port);
+    const out = { services: { [service]: svc }, networks: { default: { name: `${project}_default`, external: true } } };
+    const volumes = {};
+    for (const mount of svc.volumes || []) {
+        const source = typeof mount === 'string' ? mount.split(':')[0] : mount.source;
+        const def = source ? full.volumes?.[source] : undefined;
+        if (!source || !def)
+            continue;
+        // Named volumes keep the data the main project would use; explicit `name` / `external` volumes already do.
+        volumes[source] = def.external || def.name ? def : { ...def, external: true, name: `${project}_${source}` };
+    }
+    if (Object.keys(volumes).length)
+        out.volumes = volumes;
+    return out;
+}
+const stateFile = (dir) => path.join(dir, 'rollout.json');
+export async function loadRolloutState(dir) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(stateFile(dir), 'utf8'));
+        for (const s of Object.values(parsed.services))
+            s.draining ||= [];
+        return parsed;
+    }
+    catch {
+        return { services: {} };
+    }
+}
+async function saveRolloutState(dir, state) {
+    const tmp = `${stateFile(dir)}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, stateFile(dir));
+}
+// ---- Docker helpers ----------------------------------------------------------------------------
+/** `docker compose` arguments for a revision project, with relative paths and `.env` resolved against the main project dir. */
+export function composeBase(project, dir, file) {
+    return ['compose', '-p', project, '--project-directory', dir, '-f', file];
+}
+async function containerIds(ctx, project, service) {
+    const filters = ['--filter', `label=${LABEL_PROJECT}=${project}`, ...(service ? ['--filter', `label=${LABEL_SERVICE}=${service}`] : [])];
+    return (await ctx.docker(['ps', '-aq', ...filters])).out.split(/\s+/).filter(Boolean);
+}
+/** Stops and removes every container of a revision project (or of one service of the main project). */
+async function removeRevision(ctx, dir, project, service) {
+    const ids = await containerIds(ctx, project, service);
+    if (ids.length) {
+        await ctx.docker(['stop', ...ids]).catch(() => { });
+        await ctx.docker(['rm', '-f', ...ids]);
+    }
+    if (!service)
+        await fs.rm(path.join(dir, 'rollout', `${project}.yml`), { force: true });
+}
+async function ensureSharedResources(ctx, project, services, full) {
+    const network = `${project}_default`;
+    await ctx.docker(['network', 'inspect', network]).catch(() => ctx.docker(['network', 'create', '--label', `${LABEL_PROJECT}=${project}`, '--label', 'com.docker.compose.network=default', network]));
+    const created = new Set();
+    for (const service of services) {
+        for (const mount of full.services[service].volumes || []) {
+            const source = typeof mount === 'string' ? mount.split(':')[0] : mount.source;
+            const def = source ? full.volumes?.[source] : undefined;
+            if (!source || !def || def.external || def.name || created.has(source))
+                continue;
+            created.add(source);
+            const opts = Object.entries(def.driver_opts || {}).flatMap(([k, v]) => ['--opt', `${k}=${v}`]);
+            await ctx.docker(['volume', 'create', ...(def.driver ? ['--driver', String(def.driver)] : []), ...opts, '--label', `${LABEL_PROJECT}=${project}`, '--label', `com.docker.compose.volume=${source}`, `${project}_${source}`]);
+        }
+    }
+}
+/** Host ports already published by running containers (`0.0.0.0:20001->80/tcp, [::]:20001->80/tcp`). */
+async function publishedHostPorts(ctx) {
+    const out = (await ctx.docker(['ps', '--format', '{{.Ports}}'])).out;
+    return new Set([...out.matchAll(/:(\d+)(?:-(\d+))?->/g)].flatMap(m => {
+        const lo = Number(m[1]);
+        const hi = Number(m[2] || m[1]);
+        return Array.from({ length: Math.min(hi - lo + 1, 1000) }, (_, i) => lo + i);
+    }));
+}
+async function allocatePort(ctx, known, exclude) {
+    const [lo, hi] = parsePortRange(ctx.rolloutPorts);
+    const busy = await publishedHostPorts(ctx);
+    for (const port of [...known, ...exclude])
+        busy.add(port);
+    // Start after the newest port in use so a just-released port is not reused straight away.
+    const last = Math.max(lo - 1, ...known.filter(p => p >= lo && p <= hi));
+    const size = hi - lo + 1;
+    for (let i = 0; i < size; i++) {
+        const port = lo + ((last + 1 - lo + i) % size);
+        if (!busy.has(port))
+            return port;
+    }
+    throw new Error(`no free host port left in the rollout range ${lo}-${hi} (TUG_ROLLOUT_PORTS)`);
+}
+const PORT_CONFLICT = /port is already allocated|address already in use|bind for .* failed/i;
+function servingState(rev, extra = {}) {
+    return { rolloutState: 'serving', image: rev.image, healthyAt: now(), ...(rev.legacy ? {} : { port: rev.port }), rolloutRevision: rev.hash, ...extra };
+}
+/** True when containers of `services` still run in the main project from before they became rolling. */
+export async function hasLegacyContainers(ctx, project, services) {
+    for (const service of services)
+        if ((await containerIds(ctx, project, service)).length)
+            return true;
+    return false;
+}
+export function isRollingService(desired, service) { return isRolling(desired.compose.services[service]); }
+export async function reconcileRolling(ctx, input) {
+    const { desired, dir, services, full, deps } = input;
+    const project = desired.project;
+    const state = await loadRolloutState(dir);
+    const result = { serviceStates: {}, errors: {} };
+    await ensureDir(path.join(dir, 'rollout'));
+    // Drained revisions go first so their host ports are free for this rollout.
+    await retireRevisions(ctx, dir, state, desired, new Set(services), deps);
+    await ensureSharedResources(ctx, project, services, full);
+    for (const service of services) {
+        const rollout = state.services[service] ||= { draining: [] };
+        const spec = desired.compose.services[service];
+        const declaredPort = publishedPort(spec, spec['x-tug'].ingress.port);
+        const drainMs = parseDuration(spec['x-tug']?.rollout?.drain ?? DEFAULT_DRAIN, 30000);
+        const hash = serviceRevisionHash(desired, full.services[service], service, input.secretVersions[service]);
+        const revProject = revisionProject(project, service, hash);
+        const file = path.join(dir, 'rollout', `${revProject}.yml`);
+        const image = desired.services[service].image;
+        // A service that used to be recreated still runs in the main project: it is the revision to replace.
+        if (!rollout.active && declaredPort && (await containerIds(ctx, project, service)).length) {
+            rollout.active = { hash: 'legacy', project, port: declaredPort, image, legacy: true };
+        }
+        if (rollout.candidate && rollout.candidate.hash !== hash) {
+            await removeRevision(ctx, dir, rollout.candidate.project);
+            delete rollout.candidate;
+        }
+        const writeCompose = (port) => fs.writeFile(file, dumpYaml(rollingCompose(full, project, service, port)));
+        const up = () => ctx.docker([...composeBase(revProject, dir, file), 'up', '-d'], { cwd: dir });
+        if (rollout.active && rollout.active.hash === hash) {
+            // Steady state: make sure the revision is still up and healthy; nothing restarts when it is.
+            const active = { ...rollout.active, image };
+            try {
+                await writeCompose(active.port);
+                await up();
+                await deps.waitForHealth(revProject, service, file);
+                delete rollout.failed;
+                result.serviceStates[service] = servingState(active);
+            }
+            catch (e) {
+                result.errors[service] = errMessage(e);
+                result.serviceStates[service] = { rolloutState: 'health_checking', image, rolloutRevision: hash };
+            }
+            continue;
+        }
+        const key = `${desired.revision || desired.version}:${hash}`;
+        const reject = (error) => {
+            result.errors[service] = error;
+            result.serviceStates[service] = rollout.active ? servingState(rollout.active, { rolloutError: error }) : { rolloutState: 'health_checking', image, rolloutRevision: hash };
+        };
+        if (rollout.failed?.key === key) {
+            reject(rollout.failed.error);
+            continue;
+        }
+        try {
+            const candidate = rollout.candidate ?? { hash, project: revProject, port: await allocatePort(ctx, knownPorts(rollout), new Set()), image };
+            rollout.candidate = candidate;
+            await saveRolloutState(dir, state);
+            await deps.emit(service, 'pulling');
+            await deps.ensureArtifact(service);
+            const exclude = new Set();
+            for (let attempt = 0;; attempt++) {
+                await writeCompose(candidate.port);
+                if (!desired.services[service].artifact)
+                    await ctx.docker([...composeBase(revProject, dir, file), 'pull', service], { cwd: dir });
+                await deps.emit(service, 'starting', `starting new revision on host port ${candidate.port}`);
+                try {
+                    await up();
+                    break;
+                }
+                catch (e) {
+                    if (attempt >= 4 || !PORT_CONFLICT.test(errMessage(e)))
+                        throw e;
+                    exclude.add(candidate.port);
+                    candidate.port = await allocatePort(ctx, knownPorts(rollout), exclude);
+                    await saveRolloutState(dir, state);
+                }
+            }
+            await deps.emit(service, 'health_checking');
+            await deps.waitForHealth(revProject, service, file);
+            // Takeover: the next status report carries the new port and control re-renders the ingress.
+            if (rollout.active)
+                rollout.draining.push({ service, project: rollout.active.project, legacy: rollout.active.legacy, drainUntil: Date.now() + drainMs });
+            rollout.active = { ...candidate };
+            delete rollout.candidate;
+            delete rollout.failed;
+            await saveRolloutState(dir, state);
+            result.serviceStates[service] = servingState(rollout.active);
+            await deps.emit(service, 'serving', `new revision serving on host port ${rollout.active.port}`);
+        }
+        catch (e) {
+            const error = errMessage(e);
+            if (rollout.candidate)
+                await removeRevision(ctx, dir, rollout.candidate.project).catch(() => { });
+            delete rollout.candidate;
+            rollout.failed = { key, error };
+            await saveRolloutState(dir, state);
+            reject(error);
+            await deps.emit(service, 'rollout_failed', `new revision rejected, previous revision keeps serving: ${error}`);
+        }
+    }
+    await saveRolloutState(dir, state);
+    return result;
+}
+function knownPorts(rollout) {
+    return [rollout.active, rollout.candidate].filter((r) => Boolean(r && !r.legacy)).map(r => r.port);
+}
+/** Removes drained revisions, and revisions of services that are no longer rolling on this node. */
+async function retireRevisions(ctx, dir, state, desired, rolling, deps) {
+    for (const [service, rollout] of Object.entries(state.services)) {
+        if (!rolling.has(service)) {
+            // No longer rolling here. A service that is now recreated keeps the old revision for one drain so the switch is not abrupt.
+            const stillRuns = desired.compose.services[service] && (desired.services[service]?.placement?.nodes?.includes(ctx.nodeName) || !desired.services[service]?.placement?.nodes?.length);
+            if (rollout.candidate) {
+                await removeRevision(ctx, dir, rollout.candidate.project).catch(() => { });
+                delete rollout.candidate;
+            }
+            if (rollout.active && stillRuns) {
+                rollout.draining.push({ service, project: rollout.active.project, legacy: rollout.active.legacy, drainUntil: Date.now() + parseDuration(DEFAULT_DRAIN) });
+                delete rollout.active;
+            }
+            else if (rollout.active) {
+                await removeRevision(ctx, dir, rollout.active.project, rollout.active.legacy ? service : undefined).catch(() => { });
+                delete rollout.active;
+            }
+        }
+        const keep = [];
+        for (const old of rollout.draining) {
+            if (old.drainUntil > Date.now()) {
+                keep.push(old);
+                continue;
+            }
+            try {
+                await removeRevision(ctx, dir, old.project, old.legacy ? old.service : undefined);
+                await deps?.emit(service, 'drained', `previous revision ${old.project} removed after drain`);
+            }
+            catch {
+                keep.push(old);
+            }
+        }
+        rollout.draining = keep;
+        if (!rollout.active && !rollout.candidate && !rollout.draining.length && !rollout.failed)
+            delete state.services[service];
+    }
+}
+/** Drain/cleanup pass for a project with no rolling service left on this node (or none at all). */
+export async function retireAll(ctx, dir, desired) {
+    if (!(await fs.stat(stateFile(dir)).then(() => true, () => false)))
+        return;
+    const state = await loadRolloutState(dir);
+    await retireRevisions(ctx, dir, state, desired, new Set());
+    await saveRolloutState(dir, state);
+}
+/** Reported states for rolling services whose current revision is still serving, used when another part of the reconcile failed. */
+export async function activeRollingStates(dir, services) {
+    const state = await loadRolloutState(dir);
+    const out = {};
+    for (const service of services) {
+        const active = state.services[service]?.active;
+        if (active)
+            out[service] = servingState(active);
+    }
+    return out;
+}

package/dist/runners.d.ts

@@ -0,0 +1,12 @@
+import type { RunResult } from './build.ts';
+export type DockerRunner = (args: string[], opts?: {
+    cwd?: string;
+}) => Promise<RunResult>;
+export type HttpClient = typeof fetch;
+/** Default runner: `docker <args>` via the shared `run()` helper. */
+export declare function createDockerRunner(): DockerRunner;
+/** Runs a host binary (`wg`, `ip`); rejects on a non-zero exit like the docker runner. */
+export type HostRunner = (cmd: string, args: string[], opts?: {
+    cwd?: string;
+}) => Promise<RunResult>;
+export declare function createHostRunner(): HostRunner;

package/dist/runners.js

@@ -0,0 +1,10 @@
+// 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.
+import { run } from "./build.js";
+/** Default runner: `docker <args>` via the shared `run()` helper. */
+export function createDockerRunner() {
+    return (args, opts) => run('docker', args, opts);
+}
+export function createHostRunner() {
+    return (cmd, args, opts) => run(cmd, args, opts);
+}

package/dist/secrets.d.ts

@@ -0,0 +1,3 @@
+export declare function loadOrCreateMasterKey(file: string): Promise<string>;
+export declare function encrypt(value: unknown, masterKey: string): string;
+export declare function decrypt(payload: string, masterKey: string): string;

package/dist/secrets.js

@@ -0,0 +1,29 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { ensureDir, exists } from "./util.js";
+import path from 'node:path';
+export async function loadOrCreateMasterKey(file) {
+    await ensureDir(path.dirname(file));
+    if (await exists(file))
+        return (await fs.readFile(file, 'utf8')).trim();
+    const key = crypto.randomBytes(32).toString('base64');
+    await fs.writeFile(file, key, { mode: 0o600 });
+    return key;
+}
+function keyBytes(key) { return crypto.createHash('sha256').update(key).digest(); }
+export function encrypt(value, masterKey) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', keyBytes(masterKey), iv);
+    const encrypted = Buffer.concat([cipher.update(String(value), 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]).toString('base64');
+}
+export function decrypt(payload, masterKey) {
+    const buf = Buffer.from(payload, 'base64');
+    const iv = buf.subarray(0, 12);
+    const tag = buf.subarray(12, 28);
+    const data = buf.subarray(28);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', keyBytes(masterKey), iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+}

package/dist/templates/agent.env

@@ -0,0 +1,6 @@
+TUG_CONTROL_URL={{CONTROL_URL}}
+TUG_NODE_NAME={{NODE_NAME}}
+TUG_AGENT_TOKEN={{AGENT_TOKEN}}
+TUG_STATE_DIR=/var/lib/tug
+TUG_APPLY=true
+TUG_POLL_INTERVAL_MS=5000

package/dist/templates/control-compose.yml

@@ -0,0 +1,18 @@
+services:
+  control:
+    image: {{IMAGE}}
+    restart: unless-stopped
+    command: control
+    environment:
+      PORT: 8080
+      TUG_DATA_DIR: /data
+      TUG_OPERATOR_TOKEN: {{OPERATOR_TOKEN}}
+      TUG_REGISTRY: {{REGISTRY_HOST}}
+      TUG_REGISTRY_AUTH_PATH: {{REGISTRY_AUTH_PATH}}
+      TUG_REGISTRY_CONTAINER: {{REGISTRY_CONTAINER}}
+    ports:
+      - "{{PORT}}:8080"
+    volumes:
+      - /var/lib/tug-control:/data
+      - /var/lib/tug-registry-auth:/registry-auth
+      - /var/run/docker.sock:/var/run/docker.sock

package/dist/templates/control-install.sh

@@ -0,0 +1,7 @@
+set -eu
+mkdir -p /opt/tug-control /var/lib/tug-control
+cat > /opt/tug-control/docker-compose.yml <<'YAML'
+{{COMPOSE}}YAML
+docker compose -f /opt/tug-control/docker-compose.yml up -d
+install -m 0600 /dev/null /var/lib/tug-control/operator.token
+printf %s {{OPERATOR_TOKEN_SH}} > /var/lib/tug-control/operator.token

package/dist/templates/install-docker.sh

@@ -0,0 +1,85 @@
+set -eu
+if docker version >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then
+  echo 'Docker Engine and Compose are already available.' >&2
+  exit 0
+fi
+os_release="${TUG_OS_RELEASE:-/etc/os-release}"
+[ -r "$os_release" ] || { echo 'Docker bootstrap supports Debian, Ubuntu, Fedora and RHEL-compatible distributions with systemd.' >&2; exit 20; }
+. "$os_release"
+unsupported() { echo "Unsupported Docker bootstrap $1; install Docker Engine and Compose manually." >&2; exit 20; }
+major="${VERSION_ID:-}"; major="${major%%.*}"
+case "$ID" in
+  ubuntu|debian)
+    family=apt
+    case "$ID:${VERSION_CODENAME:-}" in
+      ubuntu:jammy|ubuntu:noble|ubuntu:resolute|ubuntu:stonking|debian:bookworm|debian:trixie) ;;
+      *) unsupported "release: $ID ${VERSION_CODENAME:-unknown}" ;;
+    esac
+    repo_os=$ID ;;
+  fedora)
+    family=dnf; repo_os=fedora
+    case "$major" in 42|43|44) ;; *) unsupported "release: $ID ${VERSION_ID:-unknown}" ;; esac ;;
+  rhel|centos|rocky|almalinux)
+    family=dnf
+    # Docker publishes one EL repository per RHEL major; Rocky, AlmaLinux and CentOS Stream use the centos one.
+    if [ "$ID" = rhel ]; then repo_os=rhel; else repo_os=centos; fi
+    case "$major" in 9|10) ;; *) unsupported "release: $ID ${VERSION_ID:-unknown}" ;; esac ;;
+  *) unsupported "OS: $ID" ;;
+esac
+# Print the selected package family and repository without touching the host (used by tests).
+if [ "${TUG_BOOTSTRAP_DETECT:-}" = 1 ]; then echo "$family $repo_os"; exit 0; fi
+[ "$(id -u)" = 0 ] || { echo 'Docker installation requires root; use a root SSH target.' >&2; exit 20; }
+[ -d /run/systemd/system ] || { echo 'Docker bootstrap requires systemd.' >&2; exit 20; }
+# Preserve existing Docker installations. Install only a missing Compose plugin.
+if command -v docker >/dev/null 2>&1; then
+  docker version >/dev/null 2>&1 || { echo 'Docker exists but is not accessible; repair/start it before installing Tug.' >&2; exit 20; }
+  engine_present=true
+else
+  engine_present=false
+fi
+conflict() { echo "Conflicting package $1 is installed; review Docker's installation instructions before replacing it." >&2; exit 20; }
+if [ "$family" = apt ]; then
+  [ -n "${VERSION_CODENAME:-}" ] || { echo 'OS release must declare VERSION_CODENAME.' >&2; exit 20; }
+  export DEBIAN_FRONTEND=noninteractive
+  if [ "$engine_present" = false ]; then
+    for package in docker.io docker-compose docker-compose-v2 podman-docker containerd runc; do
+      if dpkg-query -W -f='${Status}' "$package" 2>/dev/null | grep -q 'install ok installed'; then conflict "$package"; fi
+    done
+  fi
+  apt-get update >&2
+  apt-get install -y ca-certificates curl >&2
+  install -m 0755 -d /etc/apt/keyrings
+  curl -fsSL "https://download.docker.com/linux/$repo_os/gpg" -o /etc/apt/keyrings/docker.asc
+  chmod a+r /etc/apt/keyrings/docker.asc
+  cat > /etc/apt/sources.list.d/docker.sources <<REPO
+Types: deb
+URIs: https://download.docker.com/linux/$repo_os
+Suites: $VERSION_CODENAME
+Components: stable
+Architectures: $(dpkg --print-architecture)
+Signed-By: /etc/apt/keyrings/docker.asc
+REPO
+  apt-get update >&2
+  if [ "$engine_present" = true ]; then
+    apt-get install -y --no-upgrade --no-remove docker-compose-plugin >&2
+  else
+    apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin >&2
+  fi
+else
+  if [ "$engine_present" = false ]; then
+    for package in docker docker-client docker-client-latest docker-common docker-latest docker-logrotate docker-engine moby-engine podman-docker docker-compose; do
+      if rpm -q "$package" >/dev/null 2>&1; then conflict "$package"; fi
+    done
+  fi
+  # curl-minimal already provides curl on many EL images; installing curl over it conflicts.
+  command -v curl >/dev/null 2>&1 || dnf install -y curl >&2
+  curl -fsSL "https://download.docker.com/linux/$repo_os/docker-ce.repo" -o /etc/yum.repos.d/docker-ce.repo
+  if [ "$engine_present" = true ]; then
+    dnf install -y docker-compose-plugin >&2
+  else
+    dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin >&2
+  fi
+fi
+[ "$engine_present" = true ] || systemctl enable --now docker >&2
+docker version >/dev/null
+docker compose version >/dev/null

package/dist/templates/node-install.sh

@@ -0,0 +1,8 @@
+set -eu
+mkdir -p /etc/tug /var/lib/tug
+cat > /etc/tug/agent.env <<'ENV'
+{{ENV}}ENV
+chmod 0600 /etc/tug/agent.env
+{{DOCKER_LOGIN}}
+docker rm -f tug-agent >/dev/null 2>&1 || true
+docker run -d --name tug-agent --restart unless-stopped --env-file /etc/tug/agent.env {{RUN_FLAGS}}-v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/tug:/var/lib/tug {{IMAGE_SH}} agent

package/dist/tokens.d.ts

@@ -0,0 +1,91 @@
+import type { Request, RequestHandler } from 'express';
+import type { Db } from './db.ts';
+/** Roles are cumulative: `deploy` includes `read`, and `admin` includes both. */
+export declare const ROLES: readonly ["read", "deploy", "admin"];
+export type Role = typeof ROLES[number];
+export type RouteRole = Role | 'public';
+/** Name recorded in the audit trail for the root operator token. */
+export declare const OPERATOR_ACTOR = "operator";
+/** Reserved actor for rollbacks control starts on its own. Token names cannot contain a colon, so no token can use it. */
+export declare const AUTO_ROLLBACK_ACTOR = "system:auto-rollback";
+export declare const TOKEN_PREFIX = "tug_tok";
+export declare const TOKEN_NAME_PATTERN: RegExp;
+export declare const PROJECT_NAME_PATTERN: RegExp;
+/**
+ * The single source of truth for who may call what. Every `/api/v1` route must appear here: createApp refuses to
+ * register an unlisted route, and a test compares this table with the live router. `public` routes do their own
+ * credential check (the registry hook) and are not behind the token guard. docs/access-control.md mirrors this table.
+ */
+export declare const ROUTE_ROLES: Record<string, RouteRole>;
+/** The authenticated caller of an API request. `projects` is null when the credential is not project-scoped. */
+export interface Actor {
+    name: string;
+    role: Role;
+    projects: string[] | null;
+}
+export interface TokenRow {
+    id: string;
+    name: string;
+    token_hash: string;
+    role: Role;
+    projects_json: string | null;
+    created_at: string;
+    created_by: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+export interface TokenInfo {
+    name: string;
+    role: Role;
+    projects: string[] | null;
+    createdAt: string;
+    createdBy: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+}
+declare module 'express-serve-static-core' {
+    interface Request {
+        actor?: Actor;
+    }
+}
+export declare const isRole: (value: unknown) => value is Role;
+export declare const hasRole: (actor: Actor, required: Role) => boolean;
+/** Validates a token request body, throwing a 400 error describing the first problem. */
+export declare function parseTokenRequest(body: unknown): {
+    name: string;
+    role: Role;
+    projects: string[] | null;
+    expiresAt: string | null;
+};
+/** Creates a token. The plaintext is returned once; only its hash is stored. */
+export declare function createToken(db: Db, request: ReturnType<typeof parseTokenRequest>, createdBy: string): Promise<TokenInfo & {
+    token: string;
+}>;
+export declare function listTokens(db: Db): Promise<TokenInfo[]>;
+/** Revokes a token immediately. Returns false if no such token exists; revoking twice keeps the first revocation time. */
+export declare function revokeToken(db: Db, name: string): Promise<boolean>;
+/** Resolves a bearer value to an actor by hash lookup: the root operator token first, then named tokens. */
+export declare function authenticate(db: Db, raw: string): Promise<Actor | null>;
+/**
+ * Which project a request targets: a name, `null` for control-wide data (admin only), or `undefined` when it cannot be
+ * resolved (for example an unknown ID). Unresolvable targets are denied to scoped tokens without saying why, so they
+ * cannot probe which IDs or projects exist.
+ */
+export type ProjectResolver = (req: Request) => string | null | undefined | Promise<string | null | undefined>;
+export declare const bodyProject: ProjectResolver;
+export declare const queryProject: ProjectResolver;
+/** Throws 403 unless the actor may act on `project`. Used where the project is only known after the body is parsed. */
+export declare function assertProject(actor: Actor, project: string): void;
+/** Builds the request guard: authenticate (401), check the role (403), then check project scope (403). */
+export declare function createGuard(db: Db): (required: Role, resolve?: ProjectResolver) => RequestHandler;
+/** Appends a control-originated audit event naming the acting token. */
+export declare function recordEvent(db: Db, event: {
+    actor: string;
+    type: string;
+    message: string;
+    project?: string | null;
+    deploymentId?: string | null;
+    metadata?: Record<string, unknown>;
+}): Promise<void>;