@wpelevator/tug 0.0.0 → 0.2.0

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

@@ -0,0 +1,15 @@
+export declare const now: () => string;
+export declare const id: (prefix: string) => string;
+export declare const token: (prefix?: string) => string;
+export declare const hashToken: (value: string) => string;
+export declare function ensureDir(dir: string): Promise<void>;
+export declare function exists(p: string): Promise<boolean>;
+export declare function requireEnv(name: string, fallback?: string): string;
+export declare function projectRoot(): string;
+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

@@ -0,0 +1,35 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export const now = () => new Date().toISOString();
+export const id = (prefix) => `${prefix}_${crypto.randomBytes(8).toString('hex')}`;
+export const token = (prefix = 'tug') => `${prefix}_${crypto.randomBytes(24).toString('base64url')}`;
+export const hashToken = (value) => crypto.createHash('sha256').update(value).digest('hex');
+export async function ensureDir(dir) { await fs.mkdir(dir, { recursive: true }); }
+export async function exists(p) { try {
+    await fs.access(p);
+    return true;
+}
+catch {
+    return false;
+} }
+export function requireEnv(name, fallback) { const v = process.env[name] ?? fallback; if (!v)
+    throw new Error(`Missing ${name}`); return v; }
+export function projectRoot() { return process.cwd(); }
+export function safeJoin(base, child) { const out = path.resolve(base, child); if (!out.startsWith(path.resolve(base)))
+    throw new Error('unsafe path'); return out; }
+export function renderTemplate(str, vars) { return str.replace(/\{\{(\w+)\}\}/g, (m, key) => { if (!(key in vars))
+    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,65 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.0.0",
-  "description": "Placeholder for the Tug CLI",
-  "repository": { "type": "git", "url": "git+https://github.com/wpelevator/tug.git" }
+  "version": "0.2.0",
+  "description": "Portable VPS deployments with Docker Compose",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wpelevator/tug.git"
+  },
+  "type": "module",
+  "bin": {
+    "tug": "./dist/cli.js",
+    "tug-node": "./dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start:control": "node src/main.ts control",
+    "start:agent": "node src/main.ts agent",
+    "build": "tsc -p tsconfig.build.json && node tools/scripts/copy-templates.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "test": "node --test 'src/**/*.test.ts'",
+    "lint": "eslint .",
+    "format": "eslint . --fix",
+    "test:integration": "bash tools/scripts/integration-test.sh",
+    "test:integration:network": "bash tools/scripts/integration-network-test.sh",
+    "test:integration:agent": "node --test 'tests/integration/**/*.test.ts'",
+    "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",
+    "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",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "js-yaml": "^4.1.0",
+    "multer": "^2.2.0",
+    "sqlite": "^5.1.1",
+    "sqlite3": "^5.1.7",
+    "tar": "^7.4.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^4.17.25",
+    "@types/js-yaml": "^4.0.9",
+    "@types/multer": "^2.3.0",
+    "@types/node": "^22.20.5",
+    "eslint": "^10.5.0",
+    "globals": "^17.7.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
 }