thevoidforge 21.0.0

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

@@ -0,0 +1,5 @@
+/**
+ * Auth API — Login, logout, session check, initial setup.
+ * All responses use { success, data?, error? } format.
+ */
+export {};

package/dist/wizard/api/auth.js

@@ -0,0 +1,133 @@
+/**
+ * Auth API — Login, logout, session check, initial setup.
+ * All responses use { success, data?, error? } format.
+ */
+import { addRoute } from '../router.js';
+import { parseJsonBody } from '../lib/body-parser.js';
+import { hasUsers, createUser, login, logout, validateSession, parseSessionCookie, buildSessionCookie, clearSessionCookie, isRemoteMode, checkRateLimit, getClientIp, getUserRole, isValidUsername, } from '../lib/tower-auth.js';
+import { audit } from '../lib/audit-log.js';
+import { sendJson } from '../lib/http-helpers.js';
+// POST /api/auth/setup — Create initial admin user (only when no users exist)
+addRoute('POST', '/api/auth/setup', async (req, res) => {
+    if (!isRemoteMode()) {
+        sendJson(res, 400, { success: false, error: 'Auth setup is only available in remote mode' });
+        return;
+    }
+    // Rate-limit the setup endpoint (prevents race-to-setup attacks)
+    const ip = getClientIp(req);
+    const rateCheck = checkRateLimit(ip);
+    if (!rateCheck.allowed) {
+        sendJson(res, 429, { success: false, error: 'Too many attempts. Try again later.' });
+        return;
+    }
+    // Validate body BEFORE the hasUsers check — body parsing is not security-sensitive
+    const body = await parseJsonBody(req);
+    if (typeof body !== 'object' || body === null) {
+        sendJson(res, 400, { success: false, error: 'Request body must be a JSON object' });
+        return;
+    }
+    const { username, password } = body;
+    if (typeof username !== 'string' || !isValidUsername(username.trim())) {
+        sendJson(res, 400, { success: false, error: 'Username must be 3-64 characters (letters, numbers, . _ -)' });
+        return;
+    }
+    if (typeof password !== 'string' || password.length < 12 || password.length > 256) {
+        sendJson(res, 400, { success: false, error: 'Password must be 12-256 characters' });
+        return;
+    }
+    try {
+        // v17.0: Removed outer hasUsers() check — it was a TOCTOU race.
+        // createUser() has its own serialized hasUsers check that is atomic with creation.
+        // Two concurrent requests will serialize: the first creates, the second gets "already taken".
+        const { totpSecret, totpUri } = await createUser(username.trim(), password);
+        await audit('user_create', ip, username.trim(), { action: 'initial_setup' });
+        sendJson(res, 201, {
+            success: true,
+            data: { totpSecret, totpUri, message: 'Scan the QR code with your authenticator app.' },
+        }, true); // no-cache — TOTP secret must not be cached
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Setup failed';
+        if (message.includes('already taken')) {
+            sendJson(res, 409, { success: false, error: 'Admin user already exists' });
+        }
+        else {
+            sendJson(res, 500, { success: false, error: 'Failed to create user' });
+        }
+    }
+});
+// POST /api/auth/login — Authenticate with username + password + TOTP
+addRoute('POST', '/api/auth/login', async (req, res) => {
+    if (!isRemoteMode()) {
+        sendJson(res, 400, { success: false, error: 'Auth is only required in remote mode' });
+        return;
+    }
+    const body = await parseJsonBody(req);
+    if (typeof body !== 'object' || body === null) {
+        sendJson(res, 400, { success: false, error: 'Request body must be a JSON object' });
+        return;
+    }
+    const { username, password, totpCode } = body;
+    if (typeof username !== 'string' || typeof password !== 'string' || typeof totpCode !== 'string') {
+        sendJson(res, 400, { success: false, error: 'username, password, and totpCode are required strings' });
+        return;
+    }
+    // Cap field lengths to prevent DoS via oversized PBKDF2 input
+    // QA-R3-018 + CROSS-R4-010: TOTP must be exactly 6 digits per RFC 6238
+    if (username.length > 64 || password.length > 256 || totpCode.length !== 6 || !/^\d{6}$/.test(totpCode)) {
+        sendJson(res, 400, { success: false, error: 'Field length exceeded' });
+        return;
+    }
+    const ip = getClientIp(req);
+    await audit('login_attempt', ip, username.slice(0, 64), { method: 'password+totp' });
+    const result = await login(username, password, totpCode, ip);
+    if ('error' in result) {
+        await audit('login_failure', ip, username.slice(0, 64), { reason: result.error });
+        const status = result.retryAfterMs ? 429 : 401;
+        sendJson(res, status, { success: false, error: result.error }, true);
+        return;
+    }
+    const role = await getUserRole(username.slice(0, 64));
+    await audit('login_success', ip, username.slice(0, 64), { role: role ?? 'unknown' });
+    // Set Secure flag only when actually serving over HTTPS (proxy or direct TLS).
+    // Do NOT force Secure in remote mode — user may access via ZeroTier/Tailscale
+    // over plain HTTP without a reverse proxy. Browsers silently drop Secure cookies
+    // on HTTP, causing session loss after login. (Field report: April 2026)
+    const secure = req.headers['x-forwarded-proto'] === 'https'
+        || req.socket.encrypted === true;
+    res.setHeader('Set-Cookie', buildSessionCookie(result.token, secure));
+    sendJson(res, 200, { success: true, data: { username: username.slice(0, 64), role } }, true);
+});
+// POST /api/auth/logout — Invalidate session
+addRoute('POST', '/api/auth/logout', async (req, res) => {
+    const token = parseSessionCookie(req.headers.cookie);
+    const ip = getClientIp(req);
+    if (token) {
+        const session = validateSession(token, ip);
+        logout(token);
+        if (session) {
+            await audit('logout', ip, session.username, {});
+        }
+    }
+    res.setHeader('Set-Cookie', clearSessionCookie());
+    sendJson(res, 200, { success: true });
+});
+// GET /api/auth/session — Check if current session is valid
+addRoute('GET', '/api/auth/session', async (req, res) => {
+    if (!isRemoteMode()) {
+        sendJson(res, 200, { success: true, data: { authenticated: true, username: 'local', role: 'admin', remoteMode: false } });
+        return;
+    }
+    const token = parseSessionCookie(req.headers.cookie);
+    const ip = getClientIp(req);
+    if (!token) {
+        sendJson(res, 200, { success: true, data: { authenticated: false, needsSetup: !(await hasUsers()) } });
+        return;
+    }
+    const session = validateSession(token, ip);
+    if (!session) {
+        sendJson(res, 200, { success: true, data: { authenticated: false, needsSetup: false } });
+        return;
+    }
+    sendJson(res, 200, { success: true, data: { authenticated: true, username: session.username, role: session.role, remoteMode: true } });
+});

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

@@ -0,0 +1,45 @@
+/**
+ * Blueprint API — validates pre-written PRDs for the Blueprint Path.
+ *
+ * Provides the API endpoint for the wizard UI's blueprint auto-detection
+ * and for programmatic PRD validation.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+export interface BlueprintValidationResult {
+    valid: boolean;
+    prdFound: boolean;
+    frontmatter: Record<string, string | undefined>;
+    frontmatterErrors: string[];
+    structuralWarnings: string[];
+    conflicts: string[];
+    documents: {
+        prd: string | null;
+        projectDirectives: string | null;
+        operations: string | null;
+        adrs: string[];
+        references: string[];
+        total: number;
+    };
+    summary: string;
+}
+/**
+ * Validate a project directory for the Blueprint Path.
+ * Returns comprehensive validation results without modifying any files.
+ */
+export declare function validateBlueprint(projectRoot: string): Promise<BlueprintValidationResult>;
+export declare function executeBlueprintMerge(projectRoot: string, directivesPath: string | null): Promise<{
+    merged: boolean;
+    reason: string;
+}>;
+/**
+ * Handle blueprint API requests. Mount at /api/blueprint/*
+ *
+ * GET  /api/blueprint/detect?dir=<path>  — Check if PRD exists
+ * GET  /api/blueprint/validate?dir=<path> — Full validation
+ * POST /api/blueprint/merge — Execute CLAUDE.md merge
+ */
+export declare function handleBlueprintRequest(method: string, path: string, body: unknown): Promise<{
+    status: number;
+    body: unknown;
+} | null>;

package/dist/wizard/api/blueprint.js

@@ -0,0 +1,184 @@
+/**
+ * Blueprint API — validates pre-written PRDs for the Blueprint Path.
+ *
+ * Provides the API endpoint for the wizard UI's blueprint auto-detection
+ * and for programmatic PRD validation.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { addRoute } from '../router.js';
+import { parseFrontmatter, validateFrontmatter } from '../lib/frontmatter.js';
+import { validatePrdStructure, scanConflicts } from '../lib/prd-validator.js';
+import { discoverDocuments } from '../lib/document-discovery.js';
+import { mergeProjectDirectives, isAlreadyMerged } from '../lib/claude-merge.js';
+// ── Validation Function ─────────────────────────────
+/**
+ * Validate a project directory for the Blueprint Path.
+ * Returns comprehensive validation results without modifying any files.
+ */
+export async function validateBlueprint(projectRoot) {
+    const prdPath = join(projectRoot, 'docs/PRD.md');
+    // Check if PRD exists
+    if (!existsSync(prdPath)) {
+        return {
+            valid: false,
+            prdFound: false,
+            frontmatter: {},
+            frontmatterErrors: ['No PRD found at docs/PRD.md'],
+            structuralWarnings: [],
+            conflicts: [],
+            documents: { prd: null, projectDirectives: null, operations: null, adrs: [], references: [], total: 0 },
+            summary: 'No PRD found. Place your specification at docs/PRD.md.',
+        };
+    }
+    // Parse PRD
+    const content = await readFile(prdPath, 'utf-8');
+    const { frontmatter } = parseFrontmatter(content);
+    // Validate frontmatter
+    const frontmatterErrors = validateFrontmatter(frontmatter);
+    // Structural validation
+    const structural = validatePrdStructure(content, frontmatter);
+    // Conflict scan
+    const conflicts = scanConflicts(frontmatter);
+    // Document discovery
+    const documents = await discoverDocuments(projectRoot);
+    // Build summary
+    const summaryParts = [];
+    if (frontmatter.name)
+        summaryParts.push(`Project: ${frontmatter.name}`);
+    if (frontmatter.framework)
+        summaryParts.push(`Stack: ${frontmatter.framework}`);
+    if (frontmatter.deploy)
+        summaryParts.push(`Deploy: ${frontmatter.deploy}`);
+    summaryParts.push(`Documents: ${documents.total} found`);
+    if (frontmatterErrors.length > 0)
+        summaryParts.push(`Errors: ${frontmatterErrors.length}`);
+    if (structural.warnings.length > 0)
+        summaryParts.push(`Warnings: ${structural.warnings.length}`);
+    if (conflicts.length > 0)
+        summaryParts.push(`Conflicts: ${conflicts.length}`);
+    return {
+        valid: frontmatterErrors.length === 0,
+        prdFound: true,
+        frontmatter,
+        frontmatterErrors,
+        structuralWarnings: structural.warnings,
+        conflicts,
+        documents,
+        summary: summaryParts.join(' | '),
+    };
+}
+/**
+ * Execute the full blueprint merge (Step 3 of /blueprint).
+ * Only called after user confirms — this modifies CLAUDE.md.
+ */
+/**
+ * Validate that a relative path does not escape the project root.
+ * Prevents path traversal attacks via ../ in user-supplied paths.
+ */
+function isPathSafe(projectRoot, relativePath) {
+    if (!relativePath || relativePath.includes('..') || relativePath.startsWith('/')) {
+        return false;
+    }
+    const resolved = join(projectRoot, relativePath);
+    return resolved.startsWith(projectRoot);
+}
+export async function executeBlueprintMerge(projectRoot, directivesPath) {
+    if (!directivesPath) {
+        return { merged: false, reason: 'No project directives file discovered' };
+    }
+    // Path traversal prevention
+    if (!isPathSafe(projectRoot, directivesPath)) {
+        return { merged: false, reason: 'Invalid directives path — must be a relative path within the project' };
+    }
+    const alreadyMerged = await isAlreadyMerged(projectRoot);
+    if (alreadyMerged) {
+        return { merged: false, reason: 'Project directives already merged' };
+    }
+    const result = await mergeProjectDirectives(projectRoot, directivesPath);
+    return { merged: result.merged, reason: result.reason };
+}
+// ── Route Handler ───────────────────────────────────
+/**
+ * Handle blueprint API requests. Mount at /api/blueprint/*
+ *
+ * GET  /api/blueprint/detect?dir=<path>  — Check if PRD exists
+ * GET  /api/blueprint/validate?dir=<path> — Full validation
+ * POST /api/blueprint/merge — Execute CLAUDE.md merge
+ */
+export async function handleBlueprintRequest(method, path, body) {
+    if (method === 'GET' && path === '/api/blueprint/detect') {
+        // Quick check: does docs/PRD.md exist in the current project?
+        const projectRoot = process.cwd();
+        const prdPath = join(projectRoot, 'docs/PRD.md');
+        const exists = existsSync(prdPath);
+        if (exists) {
+            const content = await readFile(prdPath, 'utf-8');
+            const { frontmatter } = parseFrontmatter(content);
+            return {
+                status: 200,
+                body: {
+                    detected: true,
+                    name: frontmatter.name ?? 'Unnamed',
+                    description: frontmatter.type ?? 'Unknown type',
+                },
+            };
+        }
+        return { status: 200, body: { detected: false } };
+    }
+    if (method === 'GET' && path === '/api/blueprint/validate') {
+        const projectRoot = process.cwd();
+        const result = await validateBlueprint(projectRoot);
+        return { status: 200, body: result };
+    }
+    if (method === 'POST' && path === '/api/blueprint/merge') {
+        const projectRoot = process.cwd();
+        const params = body;
+        const result = await executeBlueprintMerge(projectRoot, params?.directivesPath ?? null);
+        return { status: 200, body: result };
+    }
+    return null; // Not a blueprint route
+}
+// ── JSON Response Helper ────────────────────────────
+function sendJson(res, status, data) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+}
+// ── Route Registration ──────────────────────────────
+addRoute('GET', '/api/blueprint/detect', async (_req, res) => {
+    const projectRoot = process.cwd();
+    const prdPath = join(projectRoot, 'docs/PRD.md');
+    if (existsSync(prdPath)) {
+        const content = await readFile(prdPath, 'utf-8');
+        const { frontmatter } = parseFrontmatter(content);
+        sendJson(res, 200, {
+            detected: true,
+            name: frontmatter.name ?? 'Unnamed',
+            description: frontmatter.type ?? 'Unknown type',
+        });
+    }
+    else {
+        sendJson(res, 200, { detected: false });
+    }
+});
+addRoute('GET', '/api/blueprint/validate', async (_req, res) => {
+    const projectRoot = process.cwd();
+    const result = await validateBlueprint(projectRoot);
+    sendJson(res, 200, result);
+});
+addRoute('POST', '/api/blueprint/merge', async (req, res) => {
+    let body = '';
+    for await (const chunk of req)
+        body += chunk;
+    let params = {};
+    try {
+        params = JSON.parse(body);
+    }
+    catch { /* empty body is fine — directivesPath defaults to null */ }
+    const projectRoot = process.cwd();
+    const result = await executeBlueprintMerge(projectRoot, params.directivesPath ?? null);
+    sendJson(res, 200, result);
+});

package/dist/wizard/api/cloud-providers.d.ts

@@ -0,0 +1,16 @@
+export interface ProviderInfo {
+    id: string;
+    name: string;
+    fields: {
+        key: string;
+        label: string;
+        placeholder: string;
+        secret: boolean;
+        optional?: boolean;
+    }[];
+    deployTargets: string[];
+    description: string;
+    credentialUrl: string;
+    help: string;
+}
+export declare const PROVIDERS: ProviderInfo[];