@wpelevator/tug 0.1.0 → 0.2.1

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

@@ -1,4 +1,4 @@
-set -euo pipefail
+set -eu
 mkdir -p /etc/tug /var/lib/tug
 cat > /etc/tug/agent.env <<'ENV'
 {{ENV}}ENV

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>;

package/dist/tokens.js

@@ -0,0 +1,165 @@
+import { hashToken, id, now, token } from "./util.js";
+/** Roles are cumulative: `deploy` includes `read`, and `admin` includes both. */
+export const ROLES = ['read', 'deploy', 'admin'];
+const RANK = { read: 1, deploy: 2, admin: 3 };
+/** Name recorded in the audit trail for the root operator token. */
+export 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 const AUTO_ROLLBACK_ACTOR = 'system:auto-rollback';
+export const TOKEN_PREFIX = 'tug_tok';
+export const TOKEN_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+export const PROJECT_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+/** `last_used_at` is refreshed at most this often per token, so reads do not turn into writes. */
+const LAST_USED_INTERVAL_MS = 60_000;
+/**
+ * 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 const ROUTE_ROLES = {
+    'GET /api/v1/status': 'read',
+    'GET /api/v1/events': 'read',
+    'GET /api/v1/projects/:project': 'read',
+    'GET /api/v1/deployments/:id': 'read',
+    'GET /api/v1/volumes': 'read',
+    'GET /api/v1/secrets': 'read',
+    'POST /api/v1/projects': 'deploy',
+    'POST /api/v1/deployments': 'deploy',
+    'POST /api/v1/deployments/:id/cancel': 'deploy',
+    'POST /api/v1/rollback': 'deploy',
+    'POST /api/v1/restart': 'deploy',
+    'POST /api/v1/logs': 'deploy',
+    'GET /api/v1/commands/:id': 'deploy',
+    'POST /api/v1/secrets': 'admin',
+    'DELETE /api/v1/secrets/:name': 'admin',
+    'DELETE /api/v1/volumes/:name': 'admin',
+    'GET /api/v1/nodes': 'admin',
+    'POST /api/v1/nodes/register': 'admin',
+    'POST /api/v1/nodes/enroll-token': 'admin',
+    'POST /api/v1/nodes/:name/rotate-registry-token': 'admin',
+    'POST /api/v1/nodes/:name/revoke-registry-token': 'admin',
+    'POST /api/v1/nodes/:name/rotate-wg-key': 'admin',
+    'POST /api/v1/nodes/:name/ingress': 'admin',
+    'POST /api/v1/control/backups/run': 'admin',
+    'POST /api/v1/control/restore': 'admin',
+    'GET /api/v1/diagnostics': 'admin',
+    'POST /api/v1/diagnostics/nodes': 'admin',
+    'POST /api/v1/tokens': 'admin',
+    'GET /api/v1/tokens': 'admin',
+    'DELETE /api/v1/tokens/:name': 'admin',
+    'POST /api/v1/registry/auth': 'public'
+};
+const statusError = (status, message) => Object.assign(new Error(message), { status });
+export const isRole = (value) => typeof value === 'string' && ROLES.includes(value);
+export const hasRole = (actor, required) => RANK[actor.role] >= RANK[required];
+/** Validates a token request body, throwing a 400 error describing the first problem. */
+export function parseTokenRequest(body) {
+    const input = (body && typeof body === 'object' ? body : {});
+    const { name, role, projects, expiresInSeconds } = input;
+    if (typeof name !== 'string' || !TOKEN_NAME_PATTERN.test(name))
+        throw statusError(400, 'token name must be 1-64 letters, numbers, dots, underscores or hyphens, starting with a letter or number');
+    if (name === OPERATOR_ACTOR)
+        throw statusError(400, `token name ${OPERATOR_ACTOR} is reserved for the root operator token`);
+    if (!isRole(role))
+        throw statusError(400, `role must be one of ${ROLES.join(', ')}`);
+    let scope = null;
+    if (projects !== undefined && projects !== null) {
+        if (!Array.isArray(projects) || !projects.length || projects.length > 100 || projects.some(p => typeof p !== 'string' || !PROJECT_NAME_PATTERN.test(p)))
+            throw statusError(400, 'projects must be a nonempty list of valid project names, or omitted for all projects');
+        if (role === 'admin')
+            throw statusError(400, 'admin tokens manage the whole control plane and cannot be limited to projects');
+        scope = [...new Set(projects)].sort();
+    }
+    let expiresAt = null;
+    if (expiresInSeconds !== undefined && expiresInSeconds !== null) {
+        if (typeof expiresInSeconds !== 'number' || !Number.isSafeInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 10 * 365 * 86400)
+            throw statusError(400, 'expiresInSeconds must be a positive integer of at most ten years');
+        expiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
+    }
+    return { name, role, projects: scope, expiresAt };
+}
+const info = (row) => ({ name: row.name, role: row.role, projects: row.projects_json ? JSON.parse(row.projects_json) : null, createdAt: row.created_at, createdBy: row.created_by, lastUsedAt: row.last_used_at, expiresAt: row.expires_at, revokedAt: row.revoked_at });
+/** Creates a token. The plaintext is returned once; only its hash is stored. */
+export async function createToken(db, request, createdBy) {
+    const value = token(TOKEN_PREFIX);
+    try {
+        await db.run('INSERT INTO api_tokens(id,name,token_hash,role,projects_json,created_at,created_by,expires_at) VALUES(?,?,?,?,?,?,?,?)', id('tok'), request.name, hashToken(value), request.role, request.projects ? JSON.stringify(request.projects) : null, now(), createdBy, request.expiresAt);
+    }
+    catch (e) {
+        if (/UNIQUE constraint/.test(e.message))
+            throw statusError(409, `token name ${request.name} is already used (revoked tokens keep their names for the audit trail)`);
+        throw e;
+    }
+    return { ...info((await db.get('SELECT * FROM api_tokens WHERE name=?', request.name))), token: value };
+}
+export async function listTokens(db) {
+    return (await db.all('SELECT * FROM api_tokens ORDER BY created_at, name')).map(info);
+}
+/** Revokes a token immediately. Returns false if no such token exists; revoking twice keeps the first revocation time. */
+export async function revokeToken(db, name) {
+    const row = await db.get('SELECT * FROM api_tokens WHERE name=?', name);
+    if (!row)
+        return false;
+    await db.run('UPDATE api_tokens SET revoked_at=? WHERE id=? AND revoked_at IS NULL', now(), row.id);
+    return true;
+}
+/** Resolves a bearer value to an actor by hash lookup: the root operator token first, then named tokens. */
+export async function authenticate(db, raw) {
+    if (!raw)
+        return null;
+    const hash = hashToken(raw);
+    const operator = await db.get('SELECT value FROM meta WHERE key=?', 'operator_token_hash');
+    if (operator && hash === operator.value)
+        return { name: OPERATOR_ACTOR, role: 'admin', projects: null };
+    const row = await db.get('SELECT * FROM api_tokens WHERE token_hash=?', hash);
+    if (!row || row.revoked_at || (row.expires_at && row.expires_at <= now()))
+        return null;
+    // Best effort and throttled: a slow or failing bookkeeping write must never fail or delay the request.
+    if (!row.last_used_at || Date.parse(row.last_used_at) < Date.now() - LAST_USED_INTERVAL_MS)
+        void db.run('UPDATE api_tokens SET last_used_at=? WHERE id=?', now(), row.id).catch(() => { });
+    return { name: row.name, role: row.role, projects: row.projects_json ? JSON.parse(row.projects_json) : null };
+}
+export const bodyProject = req => String(req.body?.project || 'site');
+export const queryProject = req => String(req.query.project || 'site');
+const FORBIDDEN_PROJECT = 'forbidden: this token may not access that project';
+/** Throws 403 unless the actor may act on `project`. Used where the project is only known after the body is parsed. */
+export function assertProject(actor, project) {
+    if (actor.projects && !actor.projects.includes(project))
+        throw statusError(403, FORBIDDEN_PROJECT);
+}
+/** Builds the request guard: authenticate (401), check the role (403), then check project scope (403). */
+export function createGuard(db) {
+    return (required, resolve) => async (req, res, next) => {
+        try {
+            const actor = await authenticate(db, (req.headers.authorization || '').replace(/^Bearer /, ''));
+            if (!actor) {
+                res.status(401).json({ error: 'unauthorized' });
+                return;
+            }
+            if (!hasRole(actor, required)) {
+                res.status(403).json({ error: `forbidden: this action requires the ${required} role` });
+                return;
+            }
+            if (resolve) {
+                const project = await resolve(req);
+                if (project === null && !hasRole(actor, 'admin')) {
+                    res.status(403).json({ error: 'forbidden: this action requires the admin role' });
+                    return;
+                }
+                if (actor.projects && (project === undefined || project === null || !actor.projects.includes(project))) {
+                    res.status(403).json({ error: FORBIDDEN_PROJECT });
+                    return;
+                }
+            }
+            req.actor = actor;
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/** Appends a control-originated audit event naming the acting token. */
+export async function recordEvent(db, event) {
+    await db.run('INSERT INTO events(id,project_id,deployment_id,node_id,level,type,message,metadata_json,created_at,actor) VALUES(?,?,?,?,?,?,?,?,?,?)', id('evt'), event.project ?? null, event.deploymentId ?? null, null, 'info', event.type, event.message, JSON.stringify(event.metadata ?? {}), now(), event.actor);
+}

package/dist/util.d.ts

@@ -10,3 +10,6 @@ export declare function safeJoin(base: string, child: string): string;
 export declare function renderTemplate(str: string, vars: Record<string, string>): string;
 export declare function loadTemplate(templatesDir: string, name: string, vars: Record<string, string>): Promise<string>;
 export declare const errMessage: (e: unknown) => string;
+/** Parses `500ms` / `2s` / `1m` or a millisecond number; `fallback` when it does not parse. */
+export declare function parseDuration(value: string | number, fallback?: number): number;
+export declare const isDuration: (value: unknown) => boolean;

package/dist/util.js

@@ -22,3 +22,14 @@ export function renderTemplate(str, vars) { return str.replace(/\{\{(\w+)\}\}/g,
     throw new Error(`missing template var ${key}`); return vars[key]; }); }
 export async function loadTemplate(templatesDir, name, vars) { return renderTemplate(await fs.readFile(path.join(templatesDir, name), 'utf8'), vars); }
 export const errMessage = (e) => (e instanceof Error ? e.message : String(e));
+/** Parses `500ms` / `2s` / `1m` or a millisecond number; `fallback` when it does not parse. */
+export function parseDuration(value, fallback = 2000) {
+    if (typeof value === 'number')
+        return value;
+    const m = String(value).match(/^(\d+)(ms|s|m)?$/);
+    if (!m)
+        return fallback;
+    const n = Number(m[1]);
+    return m[2] === 'm' ? n * 60000 : m[2] === 'ms' ? n : n * 1000;
+}
+export const isDuration = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0) || (typeof value === 'string' && /^\d+(ms|s|m)?$/.test(value));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Portable VPS deployments with Docker Compose",
   "repository": {
     "type": "git",
@@ -32,7 +32,10 @@
     "test:smoke:dist": "npm run build && CLI_ENTRY=dist/cli.js node --test src/cli.templates.test.ts",
     "changeset": "changeset",
     "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts",
-    "release": "changeset publish"
+    "release": "changeset publish",
+    "test:integration:rollout": "node tools/scripts/integration-rollout.js",
+    "test:integration:no-registry": "node tools/scripts/integration-no-registry.js",
+    "test:smoke:image": "node tools/scripts/smoke-runtime-image.js"
   },
   "dependencies": {
     "commander": "^12.1.0",