thevoidforge 21.0.0

package/dist/wizard/server.js

@@ -0,0 +1,436 @@
+import { createServer } from 'node:http';
+import { readFile, stat, readdir } from 'node:fs/promises';
+import { join, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { route, addRoute } from './router.js';
+// Node 20 LTS compatibility — import.meta.dirname requires Node 21.2+ (field report #122)
+// @ts-ignore — polyfill for environments where import.meta.dirname is undefined
+if (!import.meta.dirname)
+    import.meta.dirname = fileURLToPath(new URL('.', import.meta.url));
+import './api/credentials.js';
+import './api/cloud-providers.js';
+import './api/prd.js';
+import './api/project.js';
+import './api/provision.js';
+import './api/deploy.js';
+// Lazy terminal import — node-pty is a native C++ module that may not be installed (field report #122)
+try {
+    await import('./api/terminal.js');
+}
+catch {
+    console.warn('Terminal module not available (node-pty not installed). PTY features disabled.');
+}
+import './api/projects.js';
+import './api/auth.js';
+import './api/users.js';
+import './api/blueprint.js';
+import './api/danger-room.js';
+import './api/war-room.js';
+// v17.0: Register server status via addRoute for auth middleware coverage in remote mode.
+// Previously this was a hardcoded path handler that bypassed auth.
+addRoute('GET', '/api/server/status', async (_req, res) => {
+    const needsRestart = await checkNativeModulesChanged();
+    sendJson(res, 200, { needsRestart });
+});
+// Lazy import — may not exist if node-pty is not installed
+let handleTerminalUpgrade = null;
+try {
+    handleTerminalUpgrade = (await import('./api/terminal.js')).handleTerminalUpgrade;
+}
+catch { /* node-pty not available */ }
+import { handleDangerRoomUpgrade, closeDangerRoom } from './api/danger-room.js';
+import { handleWarRoomUpgrade, closeWarRoom } from './api/war-room.js';
+let killAllSessions = null;
+try {
+    killAllSessions = (await import('./lib/pty-manager.js')).killAllSessions;
+}
+catch { /* node-pty not available */ }
+import { startHealthPoller, stopHealthPoller } from './lib/health-poller.js';
+import { isPrivateOrigin } from './lib/network.js';
+import { isRemoteMode, setRemoteMode, isLanMode, setLanMode, validateSession, parseSessionCookie, isAuthExempt, getClientIp } from './lib/tower-auth.js';
+import { initAuditLog, audit } from './lib/audit-log.js';
+import { hasRole } from './lib/user-manager.js';
+// ── Route-level RBAC ────────────────────────────────
+// Maps API path prefixes to minimum required role.
+// Routes not listed here are accessible to any authenticated user.
+// Auth-exempt routes bypass this entirely (handled by isAuthExempt).
+const ROUTE_ROLES = [
+    // Admin-only: user management
+    { prefix: '/api/users/invite', minRole: 'admin' },
+    { prefix: '/api/users/remove', minRole: 'admin' },
+    { prefix: '/api/users/role', minRole: 'admin' },
+    { prefix: '/api/users', minRole: 'admin' }, // GET /api/users (list)
+    // Deployer+: infrastructure, credentials, terminals, project mutations
+    { prefix: '/api/credentials', minRole: 'deployer' },
+    { prefix: '/api/provision', minRole: 'deployer' },
+    { prefix: '/api/deploy', minRole: 'deployer' },
+    { prefix: '/api/terminal', minRole: 'deployer' },
+    { prefix: '/api/project/create', minRole: 'deployer' },
+    { prefix: '/api/projects/access', minRole: 'deployer' }, // Fine-grained owner check in handler
+    { prefix: '/api/projects/link', minRole: 'deployer' }, // Owner check in handler
+    { prefix: '/api/projects/unlink', minRole: 'deployer' }, // Owner check in handler
+    { prefix: '/api/projects/deploy-check', minRole: 'deployer' },
+    { prefix: '/api/projects/import', minRole: 'deployer' },
+    { prefix: '/api/projects/delete', minRole: 'deployer' },
+    { prefix: '/api/prd', minRole: 'deployer' },
+    { prefix: '/api/cloud', minRole: 'deployer' },
+    { prefix: '/api/deploys', minRole: 'deployer' },
+    { prefix: '/api/project/validate', minRole: 'deployer' },
+    { prefix: '/api/project/defaults', minRole: 'deployer' },
+    // Deployer+: freeze spending (safety-critical operation)
+    { prefix: '/api/danger-room/freeze', minRole: 'deployer' },
+    // Viewer: read-only endpoints (GET /api/projects, GET /api/auth/session, /api/danger-room/*) — no entry needed
+];
+function getMinRole(pathname) {
+    for (const rule of ROUTE_ROLES) {
+        if (pathname === rule.prefix || pathname.startsWith(rule.prefix + '/')) {
+            return rule.minRole;
+        }
+    }
+    return null; // No restriction — any authenticated user
+}
+const UI_DIR = join(import.meta.dirname, 'ui');
+/** Set by startServer so handleRequest can scope CORS to the actual origin. */
+// Server config shared via wizard/lib/server-config.ts (breaks circular import — Gauntlet DR-02)
+import { getServerPort, getServerHost, setServerPort, setServerHost } from './lib/server-config.js';
+const MIME_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+};
+// Use shared sendJson from http-helpers.ts — do NOT redefine here (Gauntlet DR-07)
+import { sendJson } from './lib/http-helpers.js';
+async function serveStatic(res, filePath) {
+    try {
+        const content = await readFile(filePath);
+        const ext = extname(filePath);
+        const mime = MIME_TYPES[ext] ?? 'application/octet-stream';
+        res.writeHead(200, {
+            'Content-Type': mime,
+            'Cache-Control': 'no-cache, must-revalidate',
+        });
+        res.end(content);
+    }
+    catch {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+    }
+}
+async function handleRequest(req, res) {
+    // CORS — scoped to the wizard's own origin (expanded for remote mode)
+    const origin = req.headers.origin ?? '';
+    const allowedOrigins = [`http://127.0.0.1:${getServerPort()}`, `http://localhost:${getServerPort()}`];
+    if (isRemoteMode() && getServerHost()) {
+        allowedOrigins.push(`https://${getServerHost()}`);
+    }
+    // LAN mode: accept any private IP origin (Gauntlet Picard DR-04)
+    if (allowedOrigins.includes(origin) || (isLanMode() && isPrivateOrigin(origin))) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+    }
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-VoidForge-Request');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+    res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+    // SEC-R2-003: HSTS only when actually serving HTTPS — not on plain HTTP
+    // (browsers should ignore HSTS over HTTP, but sending it is misleading)
+    if (req.headers['x-forwarded-proto'] === 'https' || req.socket.encrypted) {
+        res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+    }
+    // LAN mode: allow WebSocket from any private IP (Gauntlet Kenobi DR-10)
+    const connectSrc = isRemoteMode() && getServerHost()
+        ? `'self' ws://localhost:${getServerPort()} ws://127.0.0.1:${getServerPort()} wss://${getServerHost()}`
+        : isLanMode()
+            ? `'self' ws://localhost:${getServerPort()} ws://127.0.0.1:${getServerPort()} ws://*:${getServerPort()}`
+            : `'self' ws://localhost:${getServerPort()} ws://127.0.0.1:${getServerPort()}`;
+    res.setHeader('Content-Security-Policy', `default-src 'self'; script-src 'self' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data:; connect-src ${connectSrc} https://cdn.jsdelivr.net; frame-ancestors 'none'`);
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    // CSRF protection — require custom header on all POST requests (F-06)
+    if (req.method === 'POST' && !req.headers['x-voidforge-request']) {
+        sendJson(res, 403, { success: false, error: 'Missing X-VoidForge-Request header' });
+        return;
+    }
+    // LAN mode — restrict to dashboard-only endpoints (read-only, no credentials/deploy/terminal)
+    if (isLanMode() && !isRemoteMode()) {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const path = url.pathname;
+        const isLanSafe = path.startsWith('/api/danger-room/')
+            || path.startsWith('/api/war-room/')
+            || path === '/api/danger-room/heartbeat'
+            || path.endsWith('.html') || path.endsWith('.js') || path.endsWith('.css')
+            || path.endsWith('.svg') || path.endsWith('.png') || path.endsWith('.ico')
+            || path === '/' || path === '/danger-room.html' || path === '/war-room.html'
+            || path === '/lobby.html' || path.startsWith('/styles');
+        if (!isLanSafe) {
+            sendJson(res, 403, { success: false, error: 'Endpoint not available in LAN mode. Use --remote for full access.' });
+            return;
+        }
+    }
+    // Auth middleware — in remote mode, require valid session for non-exempt paths
+    if (isRemoteMode()) {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        if (!isAuthExempt(url.pathname)) {
+            const token = parseSessionCookie(req.headers.cookie);
+            const ip = getClientIp(req);
+            const session = token ? validateSession(token, ip) : null;
+            if (!session) {
+                // API requests get 401, page requests get redirected to login
+                if (url.pathname.startsWith('/api/')) {
+                    sendJson(res, 401, { success: false, error: 'Authentication required' });
+                }
+                else {
+                    res.writeHead(302, { Location: '/login.html' });
+                    res.end();
+                }
+                return;
+            }
+            // RBAC — check route-level minimum role
+            const minRole = getMinRole(url.pathname);
+            if (minRole && !hasRole(session, minRole)) {
+                await audit('access_denied', ip, session.username, {
+                    path: url.pathname,
+                    role: session.role,
+                    required: minRole,
+                });
+                // Return 404 not 403 — no information leakage (per CLAUDE.md)
+                sendJson(res, 404, { success: false, error: 'Not found' });
+                return;
+            }
+        }
+    }
+    // Try API routes first
+    const handler = route(req, res);
+    if (handler) {
+        try {
+            await handler(req, res);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Internal server error';
+            console.error('API error:', message);
+            sendJson(res, 500, { success: false, error: 'Internal server error' });
+        }
+        return;
+    }
+    // v17.0: /api/server/status moved to addRoute() registration below for auth middleware coverage.
+    const reqUrl = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    // Static file serving
+    const url = reqUrl;
+    let pathname = url.pathname;
+    if (pathname === '/' || pathname === '') {
+        pathname = '/lobby.html';
+    }
+    // Prevent directory traversal — resolve then verify prefix
+    const safePath = resolve(UI_DIR, '.' + pathname);
+    if (!safePath.startsWith(UI_DIR)) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+        return;
+    }
+    await serveStatic(res, safePath);
+}
+// ── Native module mtime detection (tech debt #11) ──
+// At startup, snapshot the mtimes of all .node files. On each Lobby request,
+// compare. If any changed, the server is running stale native modules.
+let nativeModuleMtimes = new Map();
+async function findNodeFiles(dir) {
+    const results = [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                results.push(...await findNodeFiles(fullPath));
+            }
+            else if (entry.name.endsWith('.node')) {
+                results.push(fullPath);
+            }
+        }
+    }
+    catch { /* skip unreadable directories */ }
+    return results;
+}
+async function snapshotNativeModules() {
+    try {
+        const nodeModulesDir = resolve(join(import.meta.dirname, '..', 'node_modules'));
+        const files = await findNodeFiles(nodeModulesDir);
+        for (const fullPath of files) {
+            const s = await stat(fullPath);
+            nativeModuleMtimes.set(fullPath, s.mtimeMs);
+        }
+    }
+    catch { /* non-fatal — if scan fails, we just can't detect changes */ }
+}
+export async function checkNativeModulesChanged() {
+    try {
+        for (const [path, mtime] of nativeModuleMtimes) {
+            const s = await stat(path);
+            if (s.mtimeMs !== mtime)
+                return true;
+        }
+    }
+    catch { /* file missing = changed */
+        return true;
+    }
+    return false;
+}
+// Module-level reference to IPv6 loopback proxy so shutdown() can close it
+let ipv6Proxy = null;
+export function startServer(port, options) {
+    setServerPort(port);
+    if (options?.remote) {
+        setRemoteMode(true);
+        setServerHost(options.host ?? '');
+    }
+    if (options?.lan) {
+        setLanMode(true);
+    }
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            handleRequest(req, res).catch((err) => {
+                console.error('Unhandled error:', err);
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end('Internal Server Error');
+                }
+            });
+        });
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                console.error(`Port ${port} is in use. Set VOIDFORGE_PORT to use a different port.`);
+                process.exit(1);
+            }
+            reject(err);
+        });
+        // WebSocket upgrade handler for terminal and Danger Room connections
+        server.on('upgrade', (req, socket, head) => {
+            console.error('[UPGRADE]', req.url, 'from', req.socket.remoteAddress);
+            const url = new URL(req.url || '', `http://localhost:${port}`);
+            if (url.pathname === '/ws/terminal') {
+                // Terminal: deployer minimum in remote mode
+                let wsSession;
+                if (isRemoteMode()) {
+                    const token = parseSessionCookie(req.headers.cookie);
+                    const ip = getClientIp(req);
+                    const session = token ? validateSession(token, ip) : null;
+                    if (!session) {
+                        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+                        socket.destroy();
+                        return;
+                    }
+                    if (!hasRole(session, 'deployer')) {
+                        socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+                        socket.destroy();
+                        return;
+                    }
+                    wsSession = session;
+                }
+                if (!handleTerminalUpgrade) {
+                    socket.write('HTTP/1.1 503 Service Unavailable\r\n\r\n');
+                    socket.destroy();
+                    return;
+                }
+                handleTerminalUpgrade(req, socket, head, wsSession);
+            }
+            else if (url.pathname === '/ws/danger-room') {
+                // Danger Room: any authenticated user in remote mode (read-only dashboard)
+                if (isRemoteMode()) {
+                    const token = parseSessionCookie(req.headers.cookie);
+                    const ip = getClientIp(req);
+                    const session = token ? validateSession(token, ip) : null;
+                    if (!session) {
+                        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+                        socket.destroy();
+                        return;
+                    }
+                }
+                handleDangerRoomUpgrade(req, socket, head);
+            }
+            else if (url.pathname === '/ws/war-room') {
+                // War Room: same auth rules as Danger Room
+                if (isRemoteMode()) {
+                    const token = parseSessionCookie(req.headers.cookie);
+                    const ip = getClientIp(req);
+                    const session = token ? validateSession(token, ip) : null;
+                    if (!session) {
+                        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+                        socket.destroy();
+                        return;
+                    }
+                }
+                handleWarRoomUpgrade(req, socket, head);
+            }
+            else {
+                socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+                socket.destroy();
+            }
+        });
+        // Local mode: bind to loopback only (PRD §9.20.1) to prevent LAN exposure of vault data.
+        // Listen on both 127.0.0.1 (IPv4) and ::1 (IPv6) — macOS resolves 'localhost' to ::1.
+        // Remote/LAN mode: bind 0.0.0.0 for external access.
+        const bindAddress = (isRemoteMode() || isLanMode()) ? '0.0.0.0' : '127.0.0.1';
+        server.listen(port, bindAddress, async () => {
+            await initAuditLog();
+            startHealthPoller();
+            await snapshotNativeModules();
+            // In local mode, also listen on IPv6 loopback so macOS 'localhost' (::1) works.
+            // TCP proxy from ::1 → 127.0.0.1 so both IPv4 and IPv6 loopback are served.
+            if (!isRemoteMode() && !isLanMode()) {
+                try {
+                    const net = await import('node:net');
+                    ipv6Proxy = net.createServer((socket) => {
+                        const upstream = net.connect({ port, host: '127.0.0.1' });
+                        socket.pipe(upstream);
+                        upstream.pipe(socket);
+                        socket.on('error', () => upstream.destroy());
+                        upstream.on('error', () => socket.destroy());
+                    });
+                    ipv6Proxy.listen(port, '::1', () => { });
+                    ipv6Proxy.on('error', () => { }); // Best-effort: IPv6 may not be available
+                }
+                catch { /* IPv6 loopback best-effort */ }
+            }
+            resolve();
+        });
+        // Graceful shutdown — stop health poller, then kill all PTY sessions
+        let shuttingDown = false;
+        const shutdown = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            console.log('\n  Shutting down...');
+            stopHealthPoller();
+            closeDangerRoom();
+            closeWarRoom();
+            killAllSessions?.();
+            if (ipv6Proxy) {
+                ipv6Proxy.close();
+                ipv6Proxy = null;
+            }
+            server.close(() => process.exit(0));
+            setTimeout(() => process.exit(0), 2000);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    });
+}
+// ── Test mode self-start ────────────────────────────
+// When VOIDFORGE_TEST=1, server.ts can be run directly: `npx tsx wizard/server.ts`
+// This enables Playwright's webServer to start the server without going through the CLI.
+if (process.env['VOIDFORGE_TEST'] === '1') {
+    const testPort = parseInt(process.env['PORT'] ?? '3199', 10);
+    startServer(testPort).then(() => {
+        console.log(`  VoidForge test server running on http://127.0.0.1:${testPort}`);
+    }).catch((err) => {
+        console.error('Test server failed to start:', err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "thevoidforge",
+  "version": "21.0.0",
+  "description": "From nothing, everything. A methodology framework for building with Claude Code.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.11.0 <25.0.0"
+  },
+  "bin": {
+    "voidforge": "./dist/scripts/voidforge.js"
+  },
+  "scripts": {
+    "wizard": "npx tsx scripts/voidforge.ts init",
+    "deploy": "npx tsx scripts/voidforge.ts deploy",
+    "build": "tsc",
+    "prepack": "bash scripts/prepack-patterns.sh && npm run build",
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run --pool forks",
+    "test:watch": "vitest --pool forks",
+    "test:coverage": "vitest run --pool forks --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:local": "playwright test --project=chromium"
+  },
+  "files": [
+    "dist/",
+    "!dist/wizard/__tests__/",
+    "!dist/wizard/e2e/",
+    "!dist/**/*.js.map",
+    "!dist/**/*.d.ts.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["voidforge", "claude-code", "methodology", "ai", "developer-tools"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tmcleod3/voidforge.git",
+    "directory": "packages/voidforge"
+  },
+  "dependencies": {
+    "@aws-sdk/client-ec2": "^3.700.0",
+    "@aws-sdk/client-elasticache": "^3.700.0",
+    "@aws-sdk/client-rds": "^3.700.0",
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/client-sts": "^3.700.0",
+    "@types/ws": "^8.18.1",
+    "node-pty": "^1.2.0-beta.12",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.1",
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.1.0"
+  }
+}