thevoidforge 21.0.0

package/dist/wizard/lib/tower-auth.js

@@ -0,0 +1,352 @@
+/**
+ * Tower Auth — Authentication engine for remote mode.
+ *
+ * 5-layer security: this module handles Layer 2 (Authentication).
+ * Two-password architecture: login password ≠ vault password.
+ *
+ * TOTP: RFC 6238, 30-second rotation, replay protection.
+ * ARCH-R2-003: Split into tower-auth + tower-session + tower-rate-limit.
+ */
+import { randomBytes, createHmac, pbkdf2 as pbkdf2Cb, timingSafeEqual } from 'node:crypto';
+import { readFile, rename, mkdir, open, copyFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// Re-export session + rate-limit modules for backward compatibility
+export { createSession, validateSession, logout, invalidateUserSessions, updateSessionRole, cleanupExpiredSessions, getSessionCookieName, parseSessionCookie, buildSessionCookie, clearSessionCookie, isAuthExempt, } from './tower-session.js';
+export { checkRateLimit, recordFailure, clearFailures, cleanupStaleEntries, } from './tower-rate-limit.js';
+// Import for internal use
+import { createSession, invalidateUserSessions, updateSessionRole, cleanupExpiredSessions } from './tower-session.js';
+import { checkRateLimit, recordFailure, clearFailures, cleanupStaleEntries } from './tower-rate-limit.js';
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+const AUTH_PATH = join(VOIDFORGE_DIR, 'auth.json');
+const MAX_USERNAME_LENGTH = 64;
+const MAX_PASSWORD_LENGTH = 256;
+// ── Configuration ──────────────────────────────────
+const TOTP_STEP = 30;
+const TOTP_DIGITS = 6;
+const PBKDF2_ITERATIONS = 210_000;
+const PBKDF2_KEYLEN = 64;
+const PBKDF2_DIGEST = 'sha512';
+const SALT_LENGTH = 32;
+const CLEANUP_INTERVAL_MS = 15 * 60 * 1000;
+// ── In-memory state ────────────────────────────────
+let remoteMode = false;
+let lanMode = false;
+let cleanupTimer = null;
+// ── Write serialization ────────────────────────────
+let writeQueue = Promise.resolve();
+function serialized(fn) {
+    const result = writeQueue.then(fn, () => fn());
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+// ── Remote + LAN mode ──────────────────────────────
+export function setRemoteMode(enabled) {
+    remoteMode = enabled;
+    if (enabled && !cleanupTimer) {
+        cleanupTimer = setInterval(() => {
+            cleanupExpiredSessions();
+            cleanupStaleEntries();
+        }, CLEANUP_INTERVAL_MS);
+        cleanupTimer.unref();
+    }
+    else if (!enabled && cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+    }
+}
+export function isRemoteMode() {
+    return remoteMode;
+}
+export function setLanMode(enabled) {
+    lanMode = enabled;
+}
+export function isLanMode() {
+    return lanMode;
+}
+/** Get client IP — delegates to rate-limit module but passes remoteMode state. */
+export function getClientIp(req) {
+    // Inline to avoid circular: trusts X-Forwarded-For only in remote mode.
+    // Use leftmost entry (parts[0]) — the real client IP before any proxies.
+    // Previously used rightmost (parts[parts.length - 1]) which returned 127.0.0.1
+    // behind Caddy, making rate limiting and session IP binding ineffective.
+    if (remoteMode) {
+        const forwarded = req.headers['x-forwarded-for'];
+        if (typeof forwarded === 'string') {
+            const parts = forwarded.split(',');
+            return parts[0].trim();
+        }
+    }
+    return req.socket.remoteAddress ?? 'unknown';
+}
+// ── Password hashing (PBKDF2, NIST-strength) ───────
+async function hashPassword(password) {
+    const capped = password.slice(0, MAX_PASSWORD_LENGTH);
+    const salt = randomBytes(SALT_LENGTH);
+    const key = await new Promise((resolve, reject) => {
+        pbkdf2Cb(capped, salt, PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST, (err, k) => {
+            if (err)
+                reject(err);
+            else
+                resolve(k);
+        });
+    });
+    return `pbkdf2:${PBKDF2_ITERATIONS}:${salt.toString('hex')}:${key.toString('hex')}`;
+}
+async function verifyPassword(password, stored) {
+    const capped = password.slice(0, MAX_PASSWORD_LENGTH);
+    const parts = stored.split(':');
+    if (parts[0] !== 'pbkdf2' || parts.length !== 4)
+        return false;
+    const iterations = parseInt(parts[1], 10);
+    const salt = Buffer.from(parts[2], 'hex');
+    const expectedKey = Buffer.from(parts[3], 'hex');
+    const actualKey = await new Promise((resolve, reject) => {
+        pbkdf2Cb(capped, salt, iterations, expectedKey.length, PBKDF2_DIGEST, (err, k) => {
+            if (err)
+                reject(err);
+            else
+                resolve(k);
+        });
+    });
+    return timingSafeEqual(actualKey, expectedKey);
+}
+// ── TOTP (RFC 6238) ────────────────────────────────
+function generateTotpSecret() {
+    const bytes = randomBytes(20);
+    return base32Encode(bytes);
+}
+function base32Encode(buffer) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+    let bits = '';
+    for (const byte of buffer) {
+        bits += byte.toString(2).padStart(8, '0');
+    }
+    let result = '';
+    for (let i = 0; i < bits.length; i += 5) {
+        const chunk = bits.slice(i, i + 5).padEnd(5, '0');
+        result += alphabet[parseInt(chunk, 2)];
+    }
+    return result;
+}
+function base32Decode(encoded) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+    let bits = '';
+    for (const char of encoded.toUpperCase()) {
+        const idx = alphabet.indexOf(char);
+        if (idx === -1)
+            continue;
+        bits += idx.toString(2).padStart(5, '0');
+    }
+    const bytes = [];
+    for (let i = 0; i + 8 <= bits.length; i += 8) {
+        bytes.push(parseInt(bits.slice(i, i + 8), 2));
+    }
+    return Buffer.from(bytes);
+}
+function generateTotp(secret, timeStep) {
+    const time = timeStep ?? Math.floor(Date.now() / 1000 / TOTP_STEP);
+    const timeBuffer = Buffer.alloc(8);
+    timeBuffer.writeUInt32BE(0, 0);
+    timeBuffer.writeUInt32BE(time, 4);
+    const key = base32Decode(secret);
+    const hmac = createHmac('sha1', key).update(timeBuffer).digest();
+    const offset = hmac[hmac.length - 1] & 0x0f;
+    const code = ((hmac[offset] & 0x7f) << 24 |
+        (hmac[offset + 1] & 0xff) << 16 |
+        (hmac[offset + 2] & 0xff) << 8 |
+        (hmac[offset + 3] & 0xff)) % (10 ** TOTP_DIGITS);
+    return code.toString().padStart(TOTP_DIGITS, '0');
+}
+function verifyTotp(secret, code, lastUsedStep) {
+    // VOIDFORGE_TEST: accept 000000 as valid TOTP for E2E test bypass
+    if (process.env['VOIDFORGE_TEST'] === '1' && code === '000000') {
+        return Math.floor(Date.now() / 1000 / TOTP_STEP);
+    }
+    const currentStep = Math.floor(Date.now() / 1000 / TOTP_STEP);
+    for (let offset = -1; offset <= 1; offset++) {
+        const step = currentStep + offset;
+        if (step <= lastUsedStep)
+            continue;
+        const expected = generateTotp(secret, step);
+        if (expected.length === code.length) {
+            const a = Buffer.from(expected);
+            const b = Buffer.from(code);
+            if (timingSafeEqual(a, b))
+                return step;
+        }
+    }
+    return -1;
+}
+// ── Auth store I/O (serialized + atomic writes) ────
+async function readAuthStore() {
+    try {
+        const raw = await readFile(AUTH_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || !Array.isArray(parsed.users)) {
+            throw new Error('Invalid auth store format');
+        }
+        for (const user of parsed.users) {
+            if (!user.role)
+                user.role = 'admin';
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return { users: [], remoteMode: false };
+        }
+        throw new Error(`Auth store corrupted: ${err instanceof Error ? err.message : 'Unknown error'}`);
+    }
+}
+async function writeAuthStore(store) {
+    await mkdir(VOIDFORGE_DIR, { recursive: true });
+    // v17.0: Backup before write — prevents lockout on corruption.
+    // Matches project-registry.ts pattern.
+    try {
+        await copyFile(AUTH_PATH, AUTH_PATH + '.bak');
+    }
+    catch { /* No existing file to backup — first write */ }
+    const data = JSON.stringify(store, null, 2);
+    const tmpPath = AUTH_PATH + '.tmp';
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(data);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, AUTH_PATH);
+}
+// ── Validation ─────────────────────────────────────
+const USERNAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
+export function isValidUsername(username) {
+    return username.length >= 3 && username.length <= MAX_USERNAME_LENGTH && USERNAME_PATTERN.test(username);
+}
+// ── Public API ─────────────────────────────────────
+export async function hasUsers() {
+    const store = await readAuthStore();
+    return store.users.length > 0;
+}
+export function createUser(username, password, role) {
+    return serialized(async () => {
+        const store = await readAuthStore();
+        const safeUsername = username.slice(0, MAX_USERNAME_LENGTH);
+        for (const user of store.users) {
+            const a = Buffer.from(user.username.padEnd(MAX_USERNAME_LENGTH));
+            const b = Buffer.from(safeUsername.padEnd(MAX_USERNAME_LENGTH));
+            if (a.length === b.length && timingSafeEqual(a, b)) {
+                throw new Error('Username already taken');
+            }
+        }
+        if (store.users.length > 0 && role === undefined) {
+            throw new Error('Invitation required for additional users');
+        }
+        const assignedRole = store.users.length === 0 ? 'admin' : role;
+        const passwordHash = await hashPassword(password);
+        const totpSecret = generateTotpSecret();
+        store.users.push({
+            username: safeUsername,
+            passwordHash,
+            totpSecret,
+            lastTotpStep: 0,
+            role: assignedRole,
+            createdAt: new Date().toISOString(),
+        });
+        store.remoteMode = true;
+        await writeAuthStore(store);
+        const totpUri = `otpauth://totp/VoidForge:${encodeURIComponent(safeUsername)}?secret=${totpSecret}&issuer=VoidForge&digits=${TOTP_DIGITS}&period=${TOTP_STEP}`;
+        return { totpSecret, totpUri };
+    });
+}
+export function removeUser(targetUsername) {
+    return serialized(async () => {
+        const store = await readAuthStore();
+        const idx = store.users.findIndex((u) => u.username === targetUsername);
+        if (idx === -1)
+            throw new Error('User not found');
+        const user = store.users[idx];
+        if (user.role === 'admin') {
+            const adminCount = store.users.filter((u) => u.role === 'admin').length;
+            if (adminCount <= 1)
+                throw new Error('Cannot remove the last admin');
+        }
+        store.users.splice(idx, 1);
+        await writeAuthStore(store);
+        invalidateUserSessions(targetUsername);
+    });
+}
+export function updateUserRole(targetUsername, newRole) {
+    return serialized(async () => {
+        const store = await readAuthStore();
+        const user = store.users.find((u) => u.username === targetUsername);
+        if (!user)
+            throw new Error('User not found');
+        if (user.role === 'admin' && newRole !== 'admin') {
+            const adminCount = store.users.filter((u) => u.role === 'admin').length;
+            if (adminCount <= 1)
+                throw new Error('Cannot demote the last admin');
+        }
+        user.role = newRole;
+        await writeAuthStore(store);
+        updateSessionRole(targetUsername, newRole);
+    });
+}
+export async function listUsers() {
+    const store = await readAuthStore();
+    return store.users.map((u) => ({
+        username: u.username,
+        role: u.role,
+        createdAt: u.createdAt,
+    }));
+}
+export async function getUserRole(username) {
+    const store = await readAuthStore();
+    const user = store.users.find((u) => u.username === username);
+    return user?.role ?? null;
+}
+export async function login(username, password, totpCode, ip) {
+    const rateCheck = checkRateLimit(ip);
+    if (!rateCheck.allowed) {
+        return { error: 'Too many attempts. Try again later.', retryAfterMs: rateCheck.retryAfterMs };
+    }
+    const safeUsername = username.slice(0, MAX_USERNAME_LENGTH);
+    const safePassword = password.slice(0, MAX_PASSWORD_LENGTH);
+    const store = await readAuthStore();
+    let matchedUser = null;
+    for (const user of store.users) {
+        const usernameA = Buffer.from(user.username.padEnd(MAX_USERNAME_LENGTH));
+        const usernameB = Buffer.from(safeUsername.padEnd(MAX_USERNAME_LENGTH));
+        if (usernameA.length === usernameB.length && timingSafeEqual(usernameA, usernameB)) {
+            matchedUser = user;
+        }
+    }
+    if (!matchedUser) {
+        await hashPassword(safePassword);
+        recordFailure(ip);
+        return { error: 'Invalid credentials' };
+    }
+    const passwordValid = await verifyPassword(safePassword, matchedUser.passwordHash);
+    if (!passwordValid) {
+        recordFailure(ip);
+        return { error: 'Invalid credentials' };
+    }
+    const usedStep = verifyTotp(matchedUser.totpSecret, totpCode, matchedUser.lastTotpStep);
+    if (usedStep === -1) {
+        recordFailure(ip);
+        return { error: 'Invalid credentials' };
+    }
+    await serialized(async () => {
+        const currentStore = await readAuthStore();
+        const user = currentStore.users.find((u) => u.username === matchedUser.username);
+        if (user) {
+            user.lastTotpStep = usedStep;
+            await writeAuthStore(currentStore);
+        }
+    });
+    clearFailures(ip);
+    const currentRole = matchedUser.role ?? 'viewer';
+    const token = createSession(matchedUser.username, currentRole, ip);
+    return { token };
+}

package/dist/wizard/lib/tower-rate-limit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tower Rate Limit — Per-IP rate limiting for login and auth endpoints.
+ * Extracted from tower-auth.ts (ARCH-R2-003).
+ *
+ * 5 attempts per 60-second window. Lockout after 10 consecutive failures (30 min).
+ */
+export declare function checkRateLimit(ip: string): {
+    allowed: boolean;
+    retryAfterMs: number;
+};
+export declare function recordFailure(ip: string): void;
+export declare function clearFailures(ip: string): void;
+/** Evict stale rate-limit entries (called by periodic cleanup). */
+export declare function cleanupStaleEntries(): void;

package/dist/wizard/lib/tower-rate-limit.js

@@ -0,0 +1,61 @@
+/**
+ * Tower Rate Limit — Per-IP rate limiting for login and auth endpoints.
+ * Extracted from tower-auth.ts (ARCH-R2-003).
+ *
+ * 5 attempts per 60-second window. Lockout after 10 consecutive failures (30 min).
+ */
+const RATE_LIMIT_WINDOW_MS = 60 * 1000;
+const RATE_LIMIT_MAX = 5;
+const LOCKOUT_THRESHOLD = 10;
+const LOCKOUT_DURATION_MS = 30 * 60 * 1000;
+const rateLimits = new Map();
+export function checkRateLimit(ip) {
+    // VOIDFORGE_TEST: skip rate limiting so E2E tests aren't throttled
+    if (process.env['VOIDFORGE_TEST'] === '1') {
+        return { allowed: true, retryAfterMs: 0 };
+    }
+    const now = Date.now();
+    const entry = rateLimits.get(ip);
+    if (!entry) {
+        rateLimits.set(ip, { attempts: 1, firstAttempt: now, consecutiveFailures: 0, lockedUntil: 0 });
+        return { allowed: true, retryAfterMs: 0 };
+    }
+    if (entry.lockedUntil > now) {
+        return { allowed: false, retryAfterMs: entry.lockedUntil - now };
+    }
+    if (now - entry.firstAttempt > RATE_LIMIT_WINDOW_MS) {
+        entry.attempts = 1;
+        entry.firstAttempt = now;
+        return { allowed: true, retryAfterMs: 0 };
+    }
+    entry.attempts++;
+    if (entry.attempts > RATE_LIMIT_MAX) {
+        return { allowed: false, retryAfterMs: RATE_LIMIT_WINDOW_MS - (now - entry.firstAttempt) };
+    }
+    return { allowed: true, retryAfterMs: 0 };
+}
+export function recordFailure(ip) {
+    const entry = rateLimits.get(ip);
+    if (!entry)
+        return;
+    entry.consecutiveFailures++;
+    if (entry.consecutiveFailures >= LOCKOUT_THRESHOLD) {
+        entry.lockedUntil = Date.now() + LOCKOUT_DURATION_MS;
+        entry.consecutiveFailures = 0;
+    }
+}
+export function clearFailures(ip) {
+    const entry = rateLimits.get(ip);
+    if (entry)
+        entry.consecutiveFailures = 0;
+}
+/** Evict stale rate-limit entries (called by periodic cleanup). */
+export function cleanupStaleEntries() {
+    const now = Date.now();
+    for (const [ip, entry] of rateLimits) {
+        if (now - entry.firstAttempt > RATE_LIMIT_WINDOW_MS && entry.lockedUntil < now) {
+            rateLimits.delete(ip);
+        }
+    }
+}
+// getClientIp removed — single source of truth is tower-auth.ts (v17.0 No Stubs cleanup)

package/dist/wizard/lib/tower-session.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tower Session — In-memory session management for remote mode.
+ * Extracted from tower-auth.ts (ARCH-R2-003).
+ *
+ * Sessions are never persisted to disk. Server restart = all sessions invalidated.
+ */
+export type UserRole = 'admin' | 'deployer' | 'viewer';
+export interface SessionInfo {
+    username: string;
+    role: UserRole;
+}
+/** Create a new session. Invalidates existing sessions for the same user. */
+export declare function createSession(username: string, role: UserRole, ip: string): string;
+/** Validate a session token. Returns session info on success, null on failure. */
+export declare function validateSession(token: string, ip: string): SessionInfo | null;
+/** Invalidate a session (logout). */
+export declare function logout(token: string): void;
+/** Invalidate all sessions for a specific user. */
+export declare function invalidateUserSessions(username: string): void;
+/** Update role on active sessions for a user. */
+export declare function updateSessionRole(username: string, newRole: UserRole): void;
+/** Evict expired sessions (called by periodic cleanup). */
+export declare function cleanupExpiredSessions(): void;
+export declare function getSessionCookieName(): string;
+export declare function parseSessionCookie(cookieHeader: string | undefined): string | null;
+export declare function buildSessionCookie(token: string, secure: boolean): string;
+export declare function clearSessionCookie(): string;
+export declare function isAuthExempt(pathname: string): boolean;

package/dist/wizard/lib/tower-session.js

@@ -0,0 +1,119 @@
+/**
+ * Tower Session — In-memory session management for remote mode.
+ * Extracted from tower-auth.ts (ARCH-R2-003).
+ *
+ * Sessions are never persisted to disk. Server restart = all sessions invalidated.
+ */
+import { randomBytes } from 'node:crypto';
+const SESSION_TTL_MS = 8 * 60 * 60 * 1000; // 8 hours
+const sessions = new Map();
+/** Create a new session. Invalidates existing sessions for the same user. */
+export function createSession(username, role, ip) {
+    // Invalidate existing sessions for this user (single active session)
+    const toDelete = [];
+    for (const [token, session] of sessions) {
+        if (session.username === username)
+            toDelete.push(token);
+    }
+    for (const token of toDelete)
+        sessions.delete(token);
+    const token = randomBytes(32).toString('hex');
+    sessions.set(token, {
+        token,
+        username,
+        role,
+        ip,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + SESSION_TTL_MS,
+        ipBinding: true,
+    });
+    return token;
+}
+/** Validate a session token. Returns session info on success, null on failure. */
+export function validateSession(token, ip) {
+    const session = sessions.get(token);
+    if (!session)
+        return null;
+    if (Date.now() > session.expiresAt) {
+        sessions.delete(token);
+        return null;
+    }
+    if (session.ipBinding && session.ip !== ip) {
+        sessions.delete(token);
+        return null;
+    }
+    return { username: session.username, role: session.role };
+}
+/** Invalidate a session (logout). */
+export function logout(token) {
+    sessions.delete(token);
+}
+/** Invalidate all sessions for a specific user. */
+export function invalidateUserSessions(username) {
+    const toDelete = [];
+    for (const [token, session] of sessions) {
+        if (session.username === username)
+            toDelete.push(token);
+    }
+    for (const token of toDelete)
+        sessions.delete(token);
+}
+/** Update role on active sessions for a user. */
+export function updateSessionRole(username, newRole) {
+    for (const [, session] of sessions) {
+        if (session.username === username)
+            session.role = newRole;
+    }
+}
+/** Evict expired sessions (called by periodic cleanup). */
+export function cleanupExpiredSessions() {
+    const now = Date.now();
+    for (const [token, session] of sessions) {
+        if (now > session.expiresAt)
+            sessions.delete(token);
+    }
+}
+// ── Cookie helpers ────────────────────────────────────
+const COOKIE_NAME = 'voidforge_session';
+export function getSessionCookieName() {
+    return COOKIE_NAME;
+}
+export function parseSessionCookie(cookieHeader) {
+    if (!cookieHeader)
+        return null;
+    const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${COOKIE_NAME}=([^;]+)`));
+    return match ? match[1] : null;
+}
+export function buildSessionCookie(token, secure) {
+    const maxAge = SESSION_TTL_MS / 1000;
+    const flags = [
+        `${COOKIE_NAME}=${token}`,
+        `Max-Age=${maxAge}`,
+        'Path=/',
+        'HttpOnly',
+        'SameSite=Strict',
+    ];
+    if (secure)
+        flags.push('Secure');
+    return flags.join('; ');
+}
+export function clearSessionCookie() {
+    return `${COOKIE_NAME}=; Max-Age=0; Path=/; HttpOnly; SameSite=Strict`;
+}
+// ── Auth exemptions ───────────────────────────────────
+const AUTH_EXEMPT_PATHS = [
+    '/api/auth/login',
+    '/api/auth/logout',
+    '/api/auth/setup',
+    '/api/auth/session',
+    '/api/users/complete-invite',
+    '/login.html',
+    '/login.js',
+    '/invite.html',
+    '/invite.js',
+    '/styles.css',
+    '/favicon.svg',
+];
+export function isAuthExempt(pathname) {
+    return AUTH_EXEMPT_PATHS.includes(pathname);
+}

package/dist/wizard/lib/treasury-backup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Treasury Backup — Encrypted daily snapshots (§9.17, §9.19.13).
+ *
+ * Daily snapshot of ~/.voidforge/treasury/ + growth state.
+ * Encrypted with vault password (AES-256-GCM).
+ * Retain 30 days. Runs as a heartbeat daemon scheduled job.
+ *
+ * PRD Reference: §9.17 (Backup Strategy), §9.19.13 (scope extension)
+ */
+/**
+ * Create an encrypted daily backup of the treasury directory.
+ * The backup is a gzipped tar-like concatenation of files, encrypted with AES-256-GCM.
+ * The vault password is the encryption key (via scrypt).
+ */
+export declare function createDailyBackup(vaultPassword: string): Promise<{
+    path: string;
+    files: number;
+}>;
+/**
+ * Export all financial data (encrypted with vault password).
+ * Used by /treasury --export and uninstall safety.
+ */
+export declare function exportTreasuryData(vaultPassword: string, outputPath: string): Promise<void>;