@wpelevator/tug 0.2.0 → 0.3.0

package/dist/tokens.js

@@ -17,6 +17,7 @@ const LAST_USED_INTERVAL_MS = 60_000;
  * 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/live': 'deploy',
     'GET /api/v1/status': 'read',
     'GET /api/v1/events': 'read',
     'GET /api/v1/projects/:project': 'read',
@@ -27,6 +28,7 @@ export const ROUTE_ROLES = {
     'POST /api/v1/deployments': 'deploy',
     'POST /api/v1/deployments/:id/cancel': 'deploy',
     'POST /api/v1/rollback': 'deploy',
+    'POST /api/v1/scale': 'deploy',
     'POST /api/v1/restart': 'deploy',
     'POST /api/v1/logs': 'deploy',
     'GET /api/v1/commands/:id': 'deploy',
@@ -40,6 +42,7 @@ export const ROUTE_ROLES = {
     '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',
+    'DELETE /api/v1/nodes/:name': 'admin',
     'POST /api/v1/control/backups/run': 'admin',
     'POST /api/v1/control/restore': 'admin',
     'GET /api/v1/diagnostics': 'admin',
@@ -47,7 +50,7 @@ export const ROUTE_ROLES = {
     'POST /api/v1/tokens': 'admin',
     'GET /api/v1/tokens': 'admin',
     'DELETE /api/v1/tokens/:name': 'admin',
-    'POST /api/v1/registry/auth': 'public'
+    '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);
@@ -64,7 +67,10 @@ export function parseTokenRequest(body) {
         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)))
+        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');
@@ -72,13 +78,25 @@ export function parseTokenRequest(body) {
     }
     let expiresAt = null;
     if (expiresInSeconds !== undefined && expiresInSeconds !== null) {
-        if (typeof expiresInSeconds !== 'number' || !Number.isSafeInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 10 * 365 * 86400)
+        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 });
+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);
@@ -90,7 +108,10 @@ export async function createToken(db, request, createdBy) {
             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 };
+    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);
@@ -117,10 +138,14 @@ export async function authenticate(db, raw) {
     // 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 };
+    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');
+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) {
@@ -146,7 +171,8 @@ export function createGuard(db) {
                     res.status(403).json({ error: 'forbidden: this action requires the admin role' });
                     return;
                 }
-                if (actor.projects && (project === undefined || project === null || !actor.projects.includes(project))) {
+                if (actor.projects &&
+                    (project === undefined || project === null || !actor.projects.includes(project))) {
                     res.status(403).json({ error: FORBIDDEN_PROJECT });
                     return;
                 }

package/dist/util.d.ts

@@ -13,3 +13,10 @@ 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;
+/**
+ * True for an IP address that is routable on the internet: anything outside loopback, private
+ * (RFC 1918, IPv6 ULA), link-local, CGNAT (`100.64.0.0/10`) and the unspecified address. The
+ * unspecified addresses `0.0.0.0` and `::` count as public, since listening there means every
+ * interface. Hostnames and other non-IP strings return false.
+ */
+export declare function isPublicAddress(address: string): boolean;

package/dist/util.js

@@ -1,26 +1,48 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { isIP } from 'node:net';
 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;
+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);
 }
-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) {
@@ -32,4 +54,39 @@ export function parseDuration(value, fallback = 2000) {
     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));
+export const isDuration = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0) ||
+    (typeof value === 'string' && /^\d+(ms|s|m)?$/.test(value));
+/**
+ * True for an IP address that is routable on the internet: anything outside loopback, private
+ * (RFC 1918, IPv6 ULA), link-local, CGNAT (`100.64.0.0/10`) and the unspecified address. The
+ * unspecified addresses `0.0.0.0` and `::` count as public, since listening there means every
+ * interface. Hostnames and other non-IP strings return false.
+ */
+export function isPublicAddress(address) {
+    const ip = address.replace(/^\[|\]$/g, '');
+    const kind = isIP(ip);
+    if (kind === 4) {
+        const [a, b] = ip.split('.').map(Number);
+        if (ip === '0.0.0.0')
+            return true;
+        return !(a === 10 ||
+            a === 127 ||
+            (a === 172 && b >= 16 && b <= 31) ||
+            (a === 192 && b === 168) ||
+            (a === 169 && b === 254) ||
+            (a === 100 && b >= 64 && b <= 127));
+    }
+    if (kind === 6) {
+        const lower = ip.toLowerCase();
+        if (lower === '::')
+            return true;
+        if (lower === '::1')
+            return false;
+        const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+        if (mapped)
+            return isPublicAddress(mapped[1]);
+        const first = Number.parseInt(lower.split(':')[0] || '0', 16);
+        return !((first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80);
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Portable VPS deployments with Docker Compose",
   "repository": {
     "type": "git",
@@ -24,8 +24,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",
     "test": "node --test 'src/**/*.test.ts'",
-    "lint": "eslint .",
-    "format": "eslint . --fix",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write . && 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'",
@@ -45,7 +45,8 @@
     "multer": "^2.2.0",
     "sqlite": "^5.1.1",
     "sqlite3": "^5.1.7",
-    "tar": "^7.4.3"
+    "tar": "^7.4.3",
+    "ws": "^8.22.1"
   },
   "devDependencies": {
     "@changesets/cli": "^3.0.3",
@@ -54,8 +55,11 @@
     "@types/js-yaml": "^4.0.9",
     "@types/multer": "^2.3.0",
     "@types/node": "^22.20.5",
+    "@types/ws": "^8.18.2",
     "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
     "globals": "^17.7.0",
+    "prettier": "^3.9.10",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.72.1"
   },