voidforge-build 23.9.1

package/dist/wizard/api/provision.js

@@ -0,0 +1,239 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { addRoute } from '../router.js';
+import { getSessionPassword } from './credentials.js';
+import { parseJsonBody } from '../lib/body-parser.js';
+import { provisioners, GITHUB_LINKED_TARGETS, GITHUB_OPTIONAL_TARGETS } from '../lib/provisioner-registry.js';
+import { createManifest, updateManifestStatus } from '../lib/provision-manifest.js';
+import { provisionDns } from '../lib/dns/cloudflare-dns.js';
+import { registerDomain } from '../lib/dns/cloudflare-registrar.js';
+import { prepareGithub } from '../lib/github.js';
+import { sshDeploy } from '../lib/ssh-deploy.js';
+import { s3Deploy } from '../lib/s3-deploy.js';
+import { runBuildStep, getBuildOutputDir } from '../lib/build-step.js';
+import { emitCostEstimate } from '../lib/cost-estimator.js';
+import { sendJson } from '../lib/http-helpers.js';
+import { provisionRuns, activeProvisionRun, setActiveProvisionRun, scopeCredentials, loadCredentials, stripSecrets, buildCleanupCredentials, } from './provision-validate.js';
+import { runPostProvisionSteps } from './provision-steps.js';
+// Barrel imports — load split route files
+import './provision-validate.js';
+import './provision-status.js';
+const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+// POST /api/provision/start — SSE stream provisioning events
+addRoute('POST', '/api/provision/start', async (req, res) => {
+    const password = getSessionPassword();
+    if (!password) {
+        sendJson(res, 401, { error: 'Vault is locked.' });
+        return;
+    }
+    // Parse and validate BEFORE acquiring the lock (IG-R2)
+    const body = await parseJsonBody(req);
+    if (body.hostname && !HOSTNAME_RE.test(body.hostname)) {
+        sendJson(res, 400, { error: 'Invalid hostname format. Expected something like: myapp.example.com' });
+        return;
+    }
+    if (!body.projectDir || !body.projectName || !body.deployTarget) {
+        sendJson(res, 400, { error: 'projectDir, projectName, and deployTarget are required' });
+        return;
+    }
+    if (!body.projectDir.startsWith('/') || body.projectDir.includes('..')) {
+        sendJson(res, 400, { error: 'projectDir must be an absolute path with no ".." segments' });
+        return;
+    }
+    try {
+        body.projectDir = await realpath(body.projectDir);
+    }
+    catch {
+        sendJson(res, 400, { error: 'Could not resolve project directory path' });
+        return;
+    }
+    const provisioner = provisioners[body.deployTarget];
+    if (!provisioner) {
+        sendJson(res, 400, { error: `Unknown deploy target: ${body.deployTarget}` });
+        return;
+    }
+    // Load credentials BEFORE lock (IG-R3)
+    let allCredentials;
+    try {
+        allCredentials = await loadCredentials(password);
+    }
+    catch {
+        sendJson(res, 500, { error: 'Failed to load credentials from vault' });
+        return;
+    }
+    const scopedCreds = scopeCredentials(allCredentials, body.deployTarget);
+    const runId = randomUUID();
+    const ctx = {
+        runId, projectDir: body.projectDir, projectName: body.projectName,
+        deployTarget: body.deployTarget, framework: (body.framework || 'express').toLowerCase(),
+        database: body.database || 'none', cache: body.cache || 'none',
+        instanceType: body.instanceType || 't3.micro', hostname: body.hostname || '',
+        credentials: scopedCreds,
+    };
+    const errors = await provisioner.validate(ctx);
+    if (errors.length > 0) {
+        sendJson(res, 400, { error: errors.join('; ') });
+        return;
+    }
+    if (activeProvisionRun) {
+        sendJson(res, 429, { error: 'A provisioning run is already in progress. Wait for it to complete.' });
+        return;
+    }
+    setActiveProvisionRun(runId);
+    // Start SSE stream
+    res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
+    let clientDisconnected = false;
+    function sseWrite(chunk) {
+        if (clientDisconnected || res.writableEnded)
+            return;
+        try {
+            res.write(chunk);
+        }
+        catch {
+            clientDisconnected = true;
+        }
+    }
+    function sseEnd() {
+        if (clientDisconnected || res.writableEnded)
+            return;
+        try {
+            res.end();
+        }
+        catch { /* already closed */ }
+    }
+    const abortController = new AbortController();
+    ctx.abortSignal = abortController.signal;
+    req.on('close', () => { clientDisconnected = true; abortController.abort(); clearInterval(keepaliveTimer); });
+    const keepaliveTimer = setInterval(() => { sseWrite(': keepalive\n\n'); }, 15000);
+    let eventId = 0;
+    const emit = (event) => { eventId++; sseWrite(`id: ${eventId}\ndata: ${JSON.stringify(event)}\n\n`); };
+    const region = allCredentials['aws-region'] || 'us-east-1';
+    await createManifest(runId, body.deployTarget, region, body.projectName);
+    const sharedOutputs = {};
+    try {
+        // ── GitHub pre-step (ADR-011) ───────────────────────────
+        const hasGithub = allCredentials['github-token'];
+        const needsGithub = GITHUB_LINKED_TARGETS.includes(body.deployTarget);
+        const wantsGithub = GITHUB_OPTIONAL_TARGETS.includes(body.deployTarget);
+        if (hasGithub && (needsGithub || wantsGithub)) {
+            const ghResult = await prepareGithub(runId, allCredentials['github-token'], allCredentials['github-owner'] || null, body.projectName, body.projectDir, emit, abortController.signal, ctx.framework, body.deployTarget);
+            if (ghResult.success) {
+                sharedOutputs['GITHUB_REPO_URL'] = ghResult.repoUrl;
+                sharedOutputs['GITHUB_OWNER'] = ghResult.owner;
+                sharedOutputs['GITHUB_REPO_NAME'] = ghResult.repoName;
+            }
+            else if (needsGithub) {
+                emit({ step: 'github-warning', status: 'error', message: `GitHub setup failed — ${body.deployTarget} project will be created without auto-deploy. Push manually later.`, detail: ghResult.error });
+            }
+        }
+        else if (!hasGithub && needsGithub) {
+            emit({ step: 'github-skip', status: 'skipped', message: `No GitHub token in vault. ${body.deployTarget} project will be created without auto-deploy. Add GitHub credentials for CI/CD.` });
+        }
+        if (sharedOutputs['GITHUB_OWNER']) {
+            ctx.credentials['_github-owner'] = sharedOutputs['GITHUB_OWNER'];
+            ctx.credentials['_github-repo-name'] = sharedOutputs['GITHUB_REPO_NAME'];
+        }
+        emitCostEstimate(body.deployTarget, ctx.instanceType, ctx.database, ctx.cache, emit);
+        const result = await provisioner.provision(ctx, emit);
+        for (const [k, v] of Object.entries(sharedOutputs)) {
+            result.outputs[k] = v;
+        }
+        // ── Pre-deploy build step (ADR-016) ─────────────────────
+        if (result.success && body.deployTarget !== 'docker') {
+            const buildResult = await runBuildStep(body.projectDir, ctx.framework, emit, abortController.signal);
+            if (!buildResult.success) {
+                emit({ step: 'build-fatal', status: 'error', message: 'Build failed — infrastructure was created, but code deploy will be skipped. Fix the build locally and deploy manually.', detail: buildResult.error });
+            }
+        }
+        // ── Deploy post-step (v3.8.0 Last Mile) ─────────────────
+        if (result.success && body.deployTarget === 'vps') {
+            const sshHost = result.outputs['SSH_HOST'];
+            if (sshHost) {
+                const deployResult = await sshDeploy(body.projectDir, sshHost, result.outputs['SSH_USER'] || 'ec2-user', result.outputs['SSH_KEY_PATH'] || '.ssh/deploy-key.pem', ctx.hostname || undefined, ctx.framework, emit, abortController.signal);
+                if (deployResult.deployUrl)
+                    result.outputs['DEPLOY_URL'] = deployResult.deployUrl;
+            }
+            else {
+                emit({ step: 'deploy-skip', status: 'skipped', message: 'No SSH host available — SSH deploy skipped' });
+            }
+        }
+        else if (result.success && body.deployTarget === 'static') {
+            const bucket = result.outputs['S3_BUCKET'], websiteUrl = result.outputs['S3_WEBSITE_URL'];
+            const awsKeyId = allCredentials['aws-access-key-id'], awsSecret = allCredentials['aws-secret-access-key'];
+            if (bucket && websiteUrl && awsKeyId && awsSecret) {
+                const s3Result = await s3Deploy(bucket, join(body.projectDir, getBuildOutputDir(ctx.framework)), allCredentials['aws-region'] || 'us-east-1', { accessKeyId: awsKeyId, secretAccessKey: awsSecret }, websiteUrl, emit);
+                if (s3Result.deployUrl)
+                    result.outputs['DEPLOY_URL'] = s3Result.deployUrl;
+            }
+            else {
+                emit({ step: 'deploy-skip', status: 'skipped', message: 'No S3 bucket available — upload skipped' });
+            }
+        }
+        else if (result.success && ['vercel', 'cloudflare', 'railway'].includes(body.deployTarget)) {
+            const deployUrl = result.outputs['DEPLOY_URL'] || result.outputs['VERCEL_DOMAIN'] || result.outputs['CF_PROJECT_URL'] || result.outputs['RAILWAY_DOMAIN'];
+            if (deployUrl && !result.outputs['DEPLOY_URL']) {
+                result.outputs['DEPLOY_URL'] = deployUrl.startsWith('http') ? deployUrl : `https://${deployUrl}`;
+            }
+        }
+        // Domain registration — pre-DNS step (non-fatal, irreversible)
+        const cfToken = allCredentials['cloudflare-api-token'], cfAccount = allCredentials['cloudflare-account-id'];
+        if (result.success && body.registerDomain && ctx.hostname && cfToken && cfAccount) {
+            const regResult = await registerDomain(cfToken, cfAccount, ctx.hostname, emit);
+            if (regResult.success) {
+                result.outputs['REGISTRAR_DOMAIN'] = regResult.domain || ctx.hostname;
+                if (regResult.expiresAt)
+                    result.outputs['REGISTRAR_EXPIRY'] = regResult.expiresAt;
+            }
+        }
+        else if (result.success && body.registerDomain && ctx.hostname && !cfAccount) {
+            emit({ step: 'registrar-skip', status: 'skipped', message: 'Domain registration requested but no Cloudflare Account ID in vault. Add it in Cloud Providers.' });
+        }
+        else if (result.success && body.registerDomain && ctx.hostname && !cfToken) {
+            emit({ step: 'registrar-skip', status: 'skipped', message: 'Domain registration requested but no Cloudflare API token in vault. Add Cloudflare credentials to enable registration.' });
+        }
+        // DNS post-provision step (non-fatal)
+        if (result.success && ctx.hostname && cfToken) {
+            const dnsResult = await provisionDns(runId, cfToken, ctx.hostname, body.deployTarget, result.outputs, emit);
+            if (dnsResult.records.length > 0) {
+                for (const record of dnsResult.records) {
+                    result.resources.push({ type: 'dns-record', id: `${dnsResult.zoneId}:${record.id}`, region: 'global' });
+                }
+                result.outputs['DNS_HOSTNAME'] = ctx.hostname;
+                result.outputs['DNS_ZONE_ID'] = dnsResult.zoneId;
+            }
+        }
+        else if (result.success && ctx.hostname && !cfToken) {
+            emit({ step: 'dns-skip', status: 'skipped', message: `Hostname "${ctx.hostname}" set but no Cloudflare token in vault. Add Cloudflare credentials to enable DNS wiring.` });
+        }
+        // Post-provision finalization (sentry, env-validator, health, deploy log)
+        if (result.success) {
+            await runPostProvisionSteps({
+                projectDir: body.projectDir, framework: ctx.framework, deployTarget: body.deployTarget,
+                projectName: body.projectName, hostname: ctx.hostname, region, runId,
+                outputs: result.outputs, resources: result.resources,
+                sentryDsn: allCredentials['sentry-dsn'], emit,
+            });
+        }
+        // Track for cleanup by run ID
+        if (result.resources.length > 0) {
+            const hasDns = result.resources.some(r => r.type === 'dns-record');
+            provisionRuns.set(runId, { resources: result.resources, credentials: buildCleanupCredentials(body.deployTarget, allCredentials, hasDns), target: body.deployTarget });
+        }
+        await updateManifestStatus(runId, result.success ? 'complete' : 'failed');
+        const safeResult = { ...result, outputs: stripSecrets(result.outputs) };
+        sseWrite(`data: ${JSON.stringify({ step: 'complete', status: result.success ? 'done' : 'error', message: result.success ? 'Provisioning complete' : result.error || 'Provisioning failed', result: safeResult, runId })}\n\n`);
+    }
+    catch (err) {
+        const errMsg = err.message;
+        console.error('Provisioning fatal error:', errMsg);
+        await updateManifestStatus(runId, 'failed');
+        sseWrite(`data: ${JSON.stringify({ step: 'fatal', status: 'error', message: 'Provisioning failed unexpectedly. Check that credentials are valid and try again.', detail: errMsg.replace(/[A-Za-z0-9+/=]{16,}/g, '***') })}\n\n`);
+    }
+    finally {
+        setActiveProvisionRun(null);
+        clearInterval(keepaliveTimer);
+        sseWrite('data: [DONE]\n\n');
+        sseEnd();
+    }
+});

package/dist/wizard/api/terminal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal API — WebSocket bridge between browser (xterm.js) and server (node-pty).
+ * Also REST endpoints for session management.
+ *
+ * WebSocket protocol:
+ *   Client → Server: raw keystrokes (text frames)
+ *   Server → Client: raw terminal output (text frames)
+ *   Client → Server: JSON control messages: { type: "resize", cols, rows }
+ *   Server → Client: JSON control messages: { type: "exit", code }
+ *
+ * Auth: vault password required in the WebSocket URL query string.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/**
+ * Handle a WebSocket upgrade request for a terminal session.
+ * URL: /ws/terminal?session=<id>&token=<authToken>
+ *
+ * Auth flow: vault password → origin check → HMAC token → session existence.
+ * Then ws library handles the protocol handshake.
+ */
+export declare function handleTerminalUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, userSession?: {
+    username: string;
+    role: 'admin' | 'deployer' | 'viewer';
+}): void;

package/dist/wizard/api/terminal.js

@@ -0,0 +1,246 @@
+/**
+ * Terminal API — WebSocket bridge between browser (xterm.js) and server (node-pty).
+ * Also REST endpoints for session management.
+ *
+ * WebSocket protocol:
+ *   Client → Server: raw keystrokes (text frames)
+ *   Server → Client: raw terminal output (text frames)
+ *   Client → Server: JSON control messages: { type: "resize", cols, rows }
+ *   Server → Client: JSON control messages: { type: "exit", code }
+ *
+ * Auth: vault password required in the WebSocket URL query string.
+ */
+import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';
+// SEC-R2-108: Per-boot random HMAC key — decoupled from vault password to prevent offline brute-force
+const TERMINAL_HMAC_KEY = randomBytes(32);
+import { WebSocketServer, WebSocket } from 'ws';
+import { access, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { addRoute } from '../router.js';
+import { getSessionPassword } from './credentials.js';
+import { getServerPort, getServerHost } from '../lib/server-config.js';
+import { parseJsonBody } from '../lib/body-parser.js';
+import { createSession, writeToSession, onSessionData, resizeSession, killSession, listSessions, } from '../lib/pty-manager.js';
+import { validateSession, parseSessionCookie, getClientIp, isRemoteMode, isLanMode } from '../lib/tower-auth.js';
+import { isPrivateOrigin } from '../lib/network.js';
+import { hasProjectAccess } from '../lib/user-manager.js';
+import { findByDirectory } from '../lib/project-registry.js';
+import { sendJson } from '../lib/http-helpers.js';
+// ── REST endpoints for session management ──────────────
+// GET /api/terminal/sessions — list active PTY sessions (filtered by project access)
+addRoute('GET', '/api/terminal/sessions', async (req, res) => {
+    const password = getSessionPassword();
+    if (!password) {
+        sendJson(res, 401, { error: 'Vault is locked.' });
+        return;
+    }
+    let allSessions = listSessions();
+    // In remote mode, filter sessions by user's project access
+    if (isRemoteMode()) {
+        const token = parseSessionCookie(req.headers.cookie);
+        const ip = getClientIp(req);
+        const userSession = token ? validateSession(token, ip) : null;
+        if (userSession && userSession.role !== 'admin') {
+            // Non-admins only see their own sessions
+            allSessions = allSessions.filter((s) => s.username === userSession.username);
+        }
+    }
+    sendJson(res, 200, { sessions: allSessions, count: allSessions.length });
+});
+// POST /api/terminal/sessions — create a new PTY session
+addRoute('POST', '/api/terminal/sessions', async (req, res) => {
+    const password = getSessionPassword();
+    if (!password) {
+        sendJson(res, 401, { error: 'Vault is locked.' });
+        return;
+    }
+    const body = await parseJsonBody(req);
+    if (!body.projectDir || !body.projectName) {
+        sendJson(res, 400, { error: 'projectDir and projectName are required' });
+        return;
+    }
+    // SEC-003/QA-002: Validate projectDir — absolute path, no traversal
+    if (!body.projectDir.startsWith('/') || body.projectDir.includes('..')) {
+        sendJson(res, 400, { error: 'projectDir must be an absolute path with no ".." segments' });
+        return;
+    }
+    // IG-R4: Resolve symlinks and use real path for all operations
+    try {
+        body.projectDir = await realpath(body.projectDir);
+    }
+    catch {
+        sendJson(res, 400, { error: 'Could not resolve project directory path' });
+        return;
+    }
+    // Verify this is a VoidForge project (CLAUDE.md exists)
+    try {
+        await access(join(body.projectDir, 'CLAUDE.md'));
+    }
+    catch {
+        sendJson(res, 400, { error: 'Not a VoidForge project — no CLAUDE.md found' });
+        return;
+    }
+    // Extract user context and check per-project access
+    let sessionUsername = '';
+    if (isRemoteMode()) {
+        const token = parseSessionCookie(req.headers.cookie);
+        const ip = getClientIp(req);
+        const userSession = token ? validateSession(token, ip) : null;
+        if (!userSession) {
+            sendJson(res, 401, { error: 'Authentication required' });
+            return;
+        }
+        sessionUsername = userSession.username;
+        // Check per-project access — deployer minimum for terminal
+        const project = await findByDirectory(body.projectDir);
+        if (!project) {
+            // Project not in registry — deny access (cannot verify permissions)
+            sendJson(res, 404, { error: 'Project not found in registry' });
+            return;
+        }
+        const projectAccess = await hasProjectAccess(userSession, project.id, 'deployer');
+        if (!projectAccess) {
+            sendJson(res, 404, { error: 'Project not found' });
+            return;
+        }
+    }
+    try {
+        const session = await createSession(body.projectDir, body.projectName, body.label || 'Shell', body.initialCommand, body.cols || 120, body.rows || 30, sessionUsername);
+        // SEC-001/SEC-002: Generate per-session auth token for WebSocket upgrade
+        const authToken = createHmac('sha256', TERMINAL_HMAC_KEY).update(session.id).digest('hex');
+        sendJson(res, 200, { session, authToken });
+    }
+    catch (err) {
+        sendJson(res, 400, { error: err.message });
+    }
+});
+// POST /api/terminal/sessions/:id/kill — kill a session (ownership check in remote mode)
+addRoute('POST', '/api/terminal/kill', async (req, res) => {
+    const password = getSessionPassword();
+    if (!password) {
+        sendJson(res, 401, { error: 'Vault is locked.' });
+        return;
+    }
+    const body = await parseJsonBody(req);
+    if (!body.sessionId) {
+        sendJson(res, 400, { error: 'sessionId is required' });
+        return;
+    }
+    // In remote mode, non-admins can only kill their own sessions
+    if (isRemoteMode()) {
+        const token = parseSessionCookie(req.headers.cookie);
+        const ip = getClientIp(req);
+        const userSession = token ? validateSession(token, ip) : null;
+        if (userSession && userSession.role !== 'admin') {
+            const sessions = listSessions();
+            const target = sessions.find((s) => s.id === body.sessionId);
+            if (!target || target.username !== userSession.username) {
+                sendJson(res, 404, { error: 'Session not found' });
+                return;
+            }
+        }
+    }
+    killSession(body.sessionId);
+    sendJson(res, 200, { killed: true });
+});
+// ── WebSocket upgrade handler (using 'ws' library) ─────
+/** Shared WebSocketServer instance — noServer mode lets us handle upgrade manually. */
+const wss = new WebSocketServer({ noServer: true });
+/**
+ * Handle a WebSocket upgrade request for a terminal session.
+ * URL: /ws/terminal?session=<id>&token=<authToken>
+ *
+ * Auth flow: vault password → origin check → HMAC token → session existence.
+ * Then ws library handles the protocol handshake.
+ */
+export function handleTerminalUpgrade(req, socket, head, userSession) {
+    void userSession;
+    const password = getSessionPassword();
+    if (!password) {
+        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    // SEC-001: Origin validation
+    const origin = req.headers.origin || '';
+    const port = getServerPort();
+    const allowedOrigins = [`http://127.0.0.1:${port}`, `http://localhost:${port}`];
+    const remoteHost = getServerHost();
+    if (remoteHost) {
+        allowedOrigins.push(`https://${remoteHost}`);
+    }
+    // LAN mode: accept any private IP origin (matches CORS handler in server.ts)
+    const isAllowed = allowedOrigins.includes(origin)
+        || (isLanMode() && isPrivateOrigin(origin));
+    if (!origin || !isAllowed) {
+        console.log(`  PTY WS rejected: origin=${origin} allowed=${JSON.stringify(allowedOrigins)} lan=${isLanMode()}`);
+        socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    const url = new URL(req.url || '', 'http://localhost');
+    const sessionId = url.searchParams.get('session');
+    if (!sessionId) {
+        socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    // SEC-002: Validate per-session auth token
+    const token = url.searchParams.get('token');
+    const expectedToken = createHmac('sha256', TERMINAL_HMAC_KEY).update(sessionId).digest('hex');
+    if (!token || token.length !== expectedToken.length || !timingSafeEqual(Buffer.from(token), Buffer.from(expectedToken))) {
+        socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    // Verify session exists
+    const sessions = listSessions();
+    if (!sessions.find((s) => s.id === sessionId)) {
+        socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    // Let the ws library handle the WebSocket handshake
+    wss.handleUpgrade(req, socket, head, (ws) => {
+        // Subscribe to PTY output → send to browser
+        const unsubscribe = onSessionData(sessionId, (data) => {
+            if (ws.readyState === WebSocket.OPEN) {
+                try {
+                    ws.send(data);
+                }
+                catch { /* client gone */ }
+            }
+        });
+        // Browser → PTY: keystrokes and control messages
+        ws.on('message', (raw) => {
+            const msg = typeof raw === 'string' ? raw : raw.toString('utf-8');
+            // JSON control messages (resize)
+            if (msg.startsWith('{')) {
+                try {
+                    const parsed = JSON.parse(msg);
+                    // IG-R2: Validate numeric types to prevent NaN propagation to node-pty
+                    if (parsed.type === 'resize' && typeof parsed.cols === 'number' && typeof parsed.rows === 'number'
+                        && Number.isFinite(parsed.cols) && Number.isFinite(parsed.rows)) {
+                        resizeSession(sessionId, parsed.cols, parsed.rows);
+                        return;
+                    }
+                }
+                catch { /* not JSON — treat as keystroke input */ }
+            }
+            // Regular input → PTY
+            try {
+                writeToSession(sessionId, msg);
+            }
+            catch {
+                ws.close();
+            }
+        });
+        ws.on('close', () => {
+            unsubscribe();
+            // Don't kill session — allow reconnection. Idle timeout handles cleanup.
+        });
+        ws.on('error', () => {
+            unsubscribe();
+        });
+    });
+}

package/dist/wizard/api/users.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Users API — Multi-user management endpoints.
+ * All user management requires admin role.
+ * Invite completion is public (token-authenticated).
+ */
+export {};