@wpelevator/tug 0.6.0 → 0.8.0

package/dist/status-report.js

@@ -0,0 +1,147 @@
+const HEALTH = ['serving', 'skipped', 'failed'];
+const ROLLOUT_STATES = [
+    'pending',
+    'pulling',
+    'starting',
+    'health_checking',
+    'serving',
+    'held',
+];
+const JOB_PHASES = [
+    'queued',
+    'pulling',
+    'checking',
+    'dumping',
+    'uploading',
+    'forgetting',
+    'restoring',
+];
+const MAX_ENTRIES = 1000;
+export class StatusReportError extends Error {
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function text(value, path, optional = false) {
+    if (value === undefined && optional)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new StatusReportError(`${path} must be a string`);
+    return value;
+}
+function list(value, path) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_ENTRIES)
+        throw new StatusReportError(`${path} must be an array of at most ${MAX_ENTRIES} entries`);
+    return value;
+}
+/** A TCP port: an integer in 1..65535, never a string, so it cannot carry configuration syntax. */
+export function isPort(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 65535;
+}
+function serviceState(value, path) {
+    if (!isObject(value))
+        throw new StatusReportError(`${path} must be an object`);
+    if (!ROLLOUT_STATES.includes(value.rolloutState))
+        throw new StatusReportError(`${path}.rolloutState must be one of ${ROLLOUT_STATES.join(', ')}`);
+    if (value.port !== undefined && !isPort(value.port))
+        throw new StatusReportError(`${path}.port must be an integer from 1 to 65535`);
+    return {
+        rolloutState: value.rolloutState,
+        ...(value.image !== undefined && { image: text(value.image, `${path}.image`) }),
+        ...(value.healthyAt !== undefined && { healthyAt: text(value.healthyAt, `${path}.healthyAt`) }),
+        ...(value.port !== undefined && { port: value.port }),
+        ...(value.rolloutRevision !== undefined && {
+            rolloutRevision: text(value.rolloutRevision, `${path}.rolloutRevision`),
+        }),
+        ...(value.rolloutError !== undefined && {
+            rolloutError: text(value.rolloutError, `${path}.rolloutError`),
+        }),
+    };
+}
+function projectStatus(value, path) {
+    if (!isObject(value))
+        throw new StatusReportError(`${path} must be an object`);
+    if (!HEALTH.includes(value.health))
+        throw new StatusReportError(`${path}.health must be one of ${HEALTH.join(', ')}`);
+    const states = value.serviceStates;
+    if (states !== undefined && !isObject(states))
+        throw new StatusReportError(`${path}.serviceStates must be an object`);
+    return {
+        project: text(value.project, `${path}.project`),
+        observedVersion: text(value.observedVersion, `${path}.observedVersion`),
+        ...(value.observedRevision !== undefined && {
+            observedRevision: text(value.observedRevision, `${path}.observedRevision`),
+        }),
+        health: value.health,
+        ...(value.services !== undefined && {
+            services: list(value.services, `${path}.services`).map((name, i) => text(name, `${path}.services[${i}]`)),
+        }),
+        ...(states && {
+            serviceStates: Object.fromEntries(Object.entries(states).map(([name, state]) => [
+                name,
+                serviceState(state, `${path}.serviceStates.${name}`),
+            ])),
+        }),
+        ...(value.error !== undefined && { error: text(value.error, `${path}.error`) }),
+    };
+}
+function commandResult(value, path) {
+    if (!isObject(value))
+        throw new StatusReportError(`${path} must be an object`);
+    if (value.state !== 'succeeded' && value.state !== 'failed')
+        throw new StatusReportError(`${path}.state must be succeeded or failed`);
+    if (value.result !== undefined && !isObject(value.result))
+        throw new StatusReportError(`${path}.result must be an object`);
+    return {
+        commandId: text(value.commandId, `${path}.commandId`),
+        state: value.state,
+        result: (value.result ?? {}),
+    };
+}
+function job(value, path) {
+    if (!isObject(value))
+        throw new StatusReportError(`${path} must be an object`);
+    if (!JOB_PHASES.includes(value.phase))
+        throw new StatusReportError(`${path}.phase must be one of ${JOB_PHASES.join(', ')}`);
+    return {
+        commandId: text(value.commandId, `${path}.commandId`),
+        runId: text(value.runId, `${path}.runId`),
+        phase: value.phase,
+        startedAt: text(value.startedAt, `${path}.startedAt`),
+        ...(typeof value.bytes === 'number' && { bytes: value.bytes }),
+    };
+}
+function ingressStatus(value) {
+    if (!isObject(value))
+        throw new StatusReportError('ingress must be an object');
+    if (value.state !== 'serving' && value.state !== 'failed')
+        throw new StatusReportError('ingress.state must be serving or failed');
+    if (typeof value.routes !== 'number' || !Number.isInteger(value.routes) || value.routes < 0)
+        throw new StatusReportError('ingress.routes must be a non-negative integer');
+    return {
+        state: value.state,
+        configHash: text(value.configHash, 'ingress.configHash'),
+        routes: value.routes,
+        ...(value.error !== undefined && { error: text(value.error, 'ingress.error') }),
+    };
+}
+/**
+ * Validates and normalizes a node's `POST /agent/v1/status` body before anything is stored. Reported values
+ * flow into other nodes' work responses and the shared ingress configuration, so unknown fields are dropped
+ * and every kept field is checked against its protocol type. Throws `StatusReportError` for a malformed report.
+ */
+export function parseStatusReport(body) {
+    if (!isObject(body))
+        throw new StatusReportError('status report must be an object');
+    return {
+        node: typeof body.node === 'string' ? body.node : '',
+        ...(typeof body.sentAt === 'string' &&
+            Number.isFinite(Date.parse(body.sentAt)) && { sentAt: body.sentAt }),
+        projects: list(body.projects, 'projects').map((p, i) => projectStatus(p, `projects[${i}]`)),
+        commandResults: list(body.commandResults, 'commandResults').map((r, i) => commandResult(r, `commandResults[${i}]`)),
+        ...(body.ingress !== undefined && { ingress: ingressStatus(body.ingress) }),
+        ...(body.jobs !== undefined && {
+            jobs: list(body.jobs, 'jobs').map((j, i) => job(j, `jobs[${i}]`)),
+        }),
+    };
+}

package/dist/templates/agent.env

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

package/dist/templates/control-compose.yml

@@ -4,12 +4,13 @@ services:
     restart: unless-stopped
     command: control
     environment:
-      PORT: 8080
+      PORT: 8443
       TUG_DATA_DIR: /data
-      TUG_OPERATOR_TOKEN: {{OPERATOR_TOKEN}}
+      TUG_PUBLIC_URL: {{PUBLIC_URL}}
+      TUG_EXTRA_SANS: {{EXTRA_SANS}}
       TUG_MESH: {{MESH}}
     ports:
-      - "{{PORT}}:8080"
+      - "{{PORT}}:8443"
     volumes:
       - /var/lib/tug-control:/data
       - /var/run/docker.sock:/var/run/docker.sock

package/dist/templates/control-install.sh

@@ -1,7 +1,13 @@
 set -eu
 mkdir -p /opt/tug-control /var/lib/tug-control
+chmod 700 /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
+# Wait for the CA so credential issuance does not race the first start.
+for i in $(seq 1 60); do
+  docker exec {{CONTAINER_SH}} test -s /data/pki/ca.crt 2>/dev/null && exit 0
+  sleep 1
+done
+echo 'control did not create its CA in time; check: docker logs {{CONTAINER_SH}}' >&2
+exit 1

package/dist/tls-server.d.ts

@@ -0,0 +1,11 @@
+import type https from 'node:https';
+/**
+ * TLS options for the single control listener: TLS 1.3, a client certificate from the pinned CA on every connection
+ * (failures end the handshake before any HTTP is parsed) and no session resumption, so each connection that carries
+ * requests has presented its certificate in a full handshake.
+ */
+export declare function serverTlsOptions(options: {
+    cert: string;
+    key: string;
+    ca: string;
+}): https.ServerOptions;

package/dist/tls-server.js

@@ -0,0 +1,23 @@
+import crypto from 'node:crypto';
+/**
+ * TLS options for the single control listener: TLS 1.3, a client certificate from the pinned CA on every connection
+ * (failures end the handshake before any HTTP is parsed) and no session resumption, so each connection that carries
+ * requests has presented its certificate in a full handshake.
+ */
+export function serverTlsOptions(options) {
+    return {
+        cert: options.cert,
+        key: options.key,
+        ca: options.ca,
+        minVersion: 'TLSv1.3',
+        maxVersion: 'TLSv1.3',
+        requestCert: true,
+        rejectUnauthorized: true,
+        // OpenSSL can fall back to stateful TLS 1.3 tickets, so the ticket option alone is not enough: the empty session
+        // id context and zero timeout make the cache refuse everything, and the gate still closes any reused session.
+        secureOptions: crypto.constants.SSL_OP_NO_TICKET,
+        sessionTimeout: 0,
+        sessionIdContext: crypto.randomBytes(16).toString('hex'),
+        handshakeTimeout: 10_000,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Portable VPS deployments with Docker Compose",
   "repository": {
     "type": "git",
@@ -9,7 +9,7 @@
   "type": "module",
   "bin": {
     "tug": "./dist/cli.js",
-    "tug-node": "./dist/main.js"
+    "tug-runtime": "./dist/main.js"
   },
   "files": [
     "dist"
@@ -39,19 +39,21 @@
     "test:smoke:image": "node tools/scripts/smoke-runtime-image.js"
   },
   "dependencies": {
-    "commander": "^12.1.0",
-    "dotenv": "^16.4.7",
-    "express": "^4.21.2",
-    "js-yaml": "^4.1.0",
+    "@peculiar/x509": "^3.1.0",
+    "commander": "^15.0.0",
+    "dotenv": "^18.0.9",
+    "express": "^5.3.0",
+    "js-yaml": "^5.5.0",
     "multer": "^2.2.0",
+    "reflect-metadata": "^0.2.2",
     "tar": "^7.4.3",
+    "undici": "^8.12.3",
     "ws": "^8.22.1"
   },
   "devDependencies": {
     "@changesets/cli": "^3.0.3",
     "@eslint/js": "^10.0.1",
-    "@types/express": "^4.17.25",
-    "@types/js-yaml": "^4.0.9",
+    "@types/express": "^5.0.6",
     "@types/multer": "^2.3.0",
     "@types/node": "^22.20.5",
     "@types/ws": "^8.18.2",

package/dist/tokens.d.ts

@@ -1,91 +0,0 @@
-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 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): TokenInfo & {
-    token: string;
-};
-export declare function listTokens(db: Db): 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): 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): 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>;
-}): void;