thevoidforge 21.0.0

package/dist/wizard/lib/templates.js

@@ -0,0 +1,219 @@
+/**
+ * Project templates — curated starters with pre-filled PRD frontmatter,
+ * recommended integrations, and seed configuration.
+ *
+ * Usage: `npx voidforge init --template saas`
+ * Or selected in Gandalf wizard Step 4 (PRD tab: "Start from a template")
+ */
+export const TEMPLATES = [
+    {
+        id: 'saas',
+        name: 'SaaS Application',
+        description: 'Multi-tenant SaaS with auth, billing, teams, and admin dashboard. Next.js + Postgres + Stripe.',
+        frontmatter: {
+            type: 'full-stack',
+            framework: 'next.js',
+            database: 'postgres',
+            cache: 'redis',
+            styling: 'tailwind',
+            auth: 'yes',
+            payments: 'stripe',
+            workers: 'yes',
+            admin: 'yes',
+            marketing: 'yes',
+            email: 'resend',
+            deploy: 'vps',
+        },
+        suggestedIntegrations: ['Stripe', 'Resend', 'S3'],
+        prdSections: `## 1. Product Vision
+
+**Name:** [PROJECT_NAME]
+**One-liner:** [Describe your SaaS in one sentence]
+**Who it's for:** [Target audience]
+
+## 2. System Architecture
+
+Multi-tenant SaaS with workspace isolation. Each tenant has their own data, billing, and team management.
+
+## 3. Tech Stack
+
+Next.js 14 (App Router), PostgreSQL, Redis, Tailwind + shadcn/ui, Prisma ORM, BullMQ workers.
+
+## 4. Core Features
+
+### 4.1 Authentication & Teams
+- Email + password signup/login (or OAuth: Google, GitHub)
+- Workspace creation on signup
+- Team invites with role-based access (owner, admin, member)
+- Session management with iron-session
+
+### 4.2 [Your Core Feature]
+[Describe the primary value proposition — the thing users pay for]
+
+### 4.3 Billing
+- Stripe Checkout for subscription creation
+- Customer portal for plan management
+- Webhook handling for subscription lifecycle (created, updated, cancelled, payment failed)
+- Free trial: 14 days, no credit card required
+- Plans: Free, Pro ($X/mo), Team ($X/mo)
+
+### 4.4 Admin Dashboard
+- User management (view, deactivate, change plan)
+- Metrics: MRR, active subscriptions, churn rate
+- Audit log of admin actions
+
+## 5. Authentication & Accounts
+[Detail auth flows, session management, OAuth providers]
+
+## 6. Database Schema
+[Prisma schema with User, Workspace, WorkspaceMember, Subscription tables]
+
+## 7. API Design
+[List all API routes with auth requirements]
+
+## 15. Deployment
+VPS with PostgreSQL, Redis, Caddy. PM2 cluster mode.`,
+    },
+    {
+        id: 'api',
+        name: 'REST API',
+        description: 'Production API with auth, rate limiting, and documentation. Express + Postgres.',
+        frontmatter: {
+            type: 'api-only',
+            framework: 'express',
+            database: 'postgres',
+            cache: 'redis',
+            styling: 'none',
+            auth: 'yes',
+            payments: 'none',
+            workers: 'no',
+            admin: 'no',
+            marketing: 'no',
+            email: 'none',
+            deploy: 'vps',
+        },
+        suggestedIntegrations: [],
+        prdSections: `## 1. Product Vision
+
+**Name:** [PROJECT_NAME]
+**One-liner:** [What does this API do?]
+**Who it's for:** [Frontend apps, mobile apps, third-party integrations]
+
+## 3. Tech Stack
+
+Express + TypeScript, PostgreSQL, Redis (caching + rate limiting), Prisma ORM.
+
+## 4. Core Features
+
+### 4.1 [Primary Resource]
+[CRUD operations for the main entity]
+
+### 4.2 Authentication
+- API key auth for server-to-server
+- JWT for user-facing clients
+- Rate limiting per key/user
+
+## 7. API Design
+[List all endpoints with methods, auth, input/output schemas]
+
+## 15. Deployment
+VPS or Docker. Caddy reverse proxy. PM2 process management.`,
+    },
+    {
+        id: 'marketing',
+        name: 'Marketing Site',
+        description: 'Fast, SEO-optimized marketing site with CMS-ready content. Next.js + Tailwind.',
+        frontmatter: {
+            type: 'static-site',
+            framework: 'next.js',
+            database: 'none',
+            cache: 'none',
+            styling: 'tailwind',
+            auth: 'no',
+            payments: 'none',
+            workers: 'no',
+            admin: 'no',
+            marketing: 'yes',
+            email: 'none',
+            deploy: 'vercel',
+        },
+        suggestedIntegrations: [],
+        prdSections: `## 1. Product Vision
+
+**Name:** [PROJECT_NAME]
+**One-liner:** [What does this site promote?]
+
+## 4. Core Features
+
+### Pages
+- Homepage (hero, features, testimonials, CTA)
+- Features / Product page
+- Pricing page (if applicable)
+- About page
+- Blog (optional — MDX or CMS)
+- Legal (privacy, terms)
+
+### SEO
+- Meta tags, Open Graph, JSON-LD
+- Sitemap, robots.txt
+- Performance: Lighthouse > 95
+
+## 14. Brand Voice
+[Tone, microcopy guidelines, visual style]
+
+## 15. Deployment
+Vercel (automatic from GitHub push).`,
+    },
+    {
+        id: 'admin',
+        name: 'Admin Dashboard',
+        description: 'Internal tool with data tables, charts, and CRUD. Next.js + Postgres + shadcn/ui.',
+        frontmatter: {
+            type: 'full-stack',
+            framework: 'next.js',
+            database: 'postgres',
+            cache: 'none',
+            styling: 'tailwind',
+            auth: 'yes',
+            payments: 'none',
+            workers: 'no',
+            admin: 'yes',
+            marketing: 'no',
+            email: 'none',
+            deploy: 'docker',
+        },
+        suggestedIntegrations: [],
+        prdSections: `## 1. Product Vision
+
+**Name:** [PROJECT_NAME]
+**One-liner:** Internal admin dashboard for [what data/operations]
+**Who it's for:** Internal team (not public-facing)
+
+## 4. Core Features
+
+### 4.1 Authentication
+- Email + password login (internal users only)
+- Role-based access: admin, viewer
+
+### 4.2 Data Management
+[List the entities this dashboard manages — users, orders, content, etc.]
+
+### 4.3 Analytics
+- Overview dashboard with key metrics
+- Charts: line (trends), bar (comparisons), stat cards
+
+## 6. Database Schema
+[Prisma schema for the data this dashboard manages]
+
+## 15. Deployment
+Docker (internal network). Or VPS with Caddy + IP allowlist.`,
+    },
+];
+/** Get a template by ID. Returns null if not found. */
+export function getTemplate(id) {
+    return TEMPLATES.find((t) => t.id === id) ?? null;
+}
+/** List all available template IDs with descriptions. */
+export function listTemplates() {
+    return TEMPLATES.map((t) => ({ id: t.id, name: t.name, description: t.description }));
+}

package/dist/wizard/lib/totp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * TOTP 2FA for financial operations.
+ *
+ * - Secret stored in system keychain (macOS Keychain / Linux Secret Service) per ADR-4
+ * - Fallback: separate encrypted file (totp.enc) with different password from vault
+ * - TOTP verification valid for 5 minutes, per-operation
+ * - Stored in process memory only (never on disk)
+ * - Replay protection: reject reuse of the same code within 30-second window
+ *
+ * PRD Reference: §9.11 (TOTP setup), ADR-4 (§9.16), §9.18 (session management)
+ *
+ * Zero dependencies — uses Node.js built-in crypto for HMAC-SHA1 (RFC 6238).
+ */
+/** Generate a new TOTP secret (160 bits per RFC 4226) */
+export declare function generateSecret(): Buffer;
+/** Encode secret as base32 for authenticator apps */
+export declare function encodeBase32(buffer: Buffer): string;
+/** Generate the otpauth:// URI for QR code / manual entry */
+export declare function generateOtpauthUri(secret: Buffer, issuer?: string, account?: string): string;
+/** Set up TOTP — generates secret, stores in keychain, returns URI for QR display */
+export declare function totpSetup(fallbackPassword?: string): Promise<{
+    uri: string;
+    secret: string;
+    stored: 'keychain' | 'file';
+}>;
+/** Verify a TOTP code. Returns true if valid, false if invalid or replay. */
+export declare function totpVerify(code: string, fallbackPassword?: string): Promise<boolean>;
+/** Check if a TOTP session is still valid (5 min TTL, 2 min idle) */
+export declare function totpSessionValid(): boolean;
+/** Invalidate the TOTP session */
+export declare function totpSessionInvalidate(): void;
+/** Check if TOTP is configured (keychain or file) */
+export declare function totpIsConfigured(fallbackPassword?: string): Promise<boolean>;
+/** Remove TOTP configuration */
+export declare function totpRemove(): Promise<void>;

package/dist/wizard/lib/totp.js

@@ -0,0 +1,276 @@
+/**
+ * TOTP 2FA for financial operations.
+ *
+ * - Secret stored in system keychain (macOS Keychain / Linux Secret Service) per ADR-4
+ * - Fallback: separate encrypted file (totp.enc) with different password from vault
+ * - TOTP verification valid for 5 minutes, per-operation
+ * - Stored in process memory only (never on disk)
+ * - Replay protection: reject reuse of the same code within 30-second window
+ *
+ * PRD Reference: §9.11 (TOTP setup), ADR-4 (§9.16), §9.18 (session management)
+ *
+ * Zero dependencies — uses Node.js built-in crypto for HMAC-SHA1 (RFC 6238).
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFile, open, rename, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { execSync } from 'node:child_process';
+const TREASURY_DIR = join(homedir(), '.voidforge', 'treasury');
+const TOTP_FALLBACK_PATH = join(TREASURY_DIR, 'totp.enc');
+const KEYCHAIN_SERVICE = 'com.voidforge.totp';
+const KEYCHAIN_ACCOUNT = 'totp-secret';
+// TOTP parameters (RFC 6238)
+const TOTP_PERIOD = 30; // seconds
+const TOTP_DIGITS = 6;
+const TOTP_ALGORITHM = 'sha1'; // per RFC 6238
+// Session management (§9.18)
+const TOTP_SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const TOTP_IDLE_TTL_MS = 2 * 60 * 1000; // 2 minutes idle → invalidate
+const TOTP_WINDOW = 1; // accept ±1 time step (30s tolerance)
+let session = null;
+// ── TOTP Generation (RFC 6238) ────────────────────────
+function generateTotpCode(secret, timeStep) {
+    const timeBuffer = Buffer.alloc(8);
+    timeBuffer.writeBigInt64BE(BigInt(timeStep));
+    const hmac = createHmac(TOTP_ALGORITHM, secret);
+    hmac.update(timeBuffer);
+    const hash = hmac.digest();
+    // Dynamic truncation (RFC 4226 §5.4)
+    const offset = hash[hash.length - 1] & 0x0f;
+    const binary = ((hash[offset] & 0x7f) << 24) |
+        ((hash[offset + 1] & 0xff) << 16) |
+        ((hash[offset + 2] & 0xff) << 8) |
+        (hash[offset + 3] & 0xff);
+    const otp = binary % Math.pow(10, TOTP_DIGITS);
+    return otp.toString().padStart(TOTP_DIGITS, '0');
+}
+function getCurrentStep() {
+    return Math.floor(Date.now() / 1000 / TOTP_PERIOD);
+}
+// ── Secret Management ─────────────────────────────────
+/** Generate a new TOTP secret (160 bits per RFC 4226) */
+export function generateSecret() {
+    return randomBytes(20); // 160 bits
+}
+/** Encode secret as base32 for authenticator apps */
+export function encodeBase32(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.substring(i, i + 5).padEnd(5, '0');
+        result += alphabet[parseInt(chunk, 2)];
+    }
+    return result;
+}
+/** Generate the otpauth:// URI for QR code / manual entry */
+export function generateOtpauthUri(secret, issuer = 'VoidForge', account = 'treasury') {
+    const b32 = encodeBase32(secret);
+    return `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(account)}?secret=${b32}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=${TOTP_DIGITS}&period=${TOTP_PERIOD}`;
+}
+// ── Keychain Storage (ADR-4) ──────────────────────────
+/** Store TOTP secret in system keychain (macOS) */
+async function storeInKeychain(secret) {
+    if (platform() !== 'darwin')
+        return false;
+    try {
+        // Delete existing entry if present
+        try {
+            execSync(`security delete-generic-password -s "${KEYCHAIN_SERVICE}" -a "${KEYCHAIN_ACCOUNT}" 2>/dev/null`);
+        }
+        catch { /* not found — fine */ }
+        const hex = secret.toString('hex');
+        execSync(`security add-generic-password -s "${KEYCHAIN_SERVICE}" -a "${KEYCHAIN_ACCOUNT}" -w "${hex}" -T ""`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read TOTP secret from system keychain (macOS) */
+async function readFromKeychain() {
+    if (platform() !== 'darwin')
+        return null;
+    try {
+        const hex = execSync(`security find-generic-password -s "${KEYCHAIN_SERVICE}" -a "${KEYCHAIN_ACCOUNT}" -w 2>/dev/null`, { encoding: 'utf-8' }).trim();
+        return Buffer.from(hex, 'hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** Delete TOTP secret from system keychain */
+async function deleteFromKeychain() {
+    if (platform() !== 'darwin')
+        return;
+    try {
+        execSync(`security delete-generic-password -s "${KEYCHAIN_SERVICE}" -a "${KEYCHAIN_ACCOUNT}" 2>/dev/null`);
+    }
+    catch { /* not found — fine */ }
+}
+// ── Fallback: Encrypted File ──────────────────────────
+// Used when system keychain is unavailable (Linux without Secret Service, etc.)
+// Encrypted with a DIFFERENT password from the financial vault (§9.11)
+async function storeInFile(secret, totpPassword) {
+    // Re-use the financial vault's encrypt pattern but with a separate password
+    const { createCipheriv, scrypt: scryptCb } = await import('node:crypto');
+    const salt = randomBytes(32);
+    const iv = randomBytes(16);
+    const key = await new Promise((resolve, reject) => {
+        scryptCb(totpPassword.slice(0, 256), salt, 32, { N: 131072, r: 8, p: 1 }, (err, k) => {
+            if (err)
+                reject(err);
+            else
+                resolve(k);
+        });
+    });
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(secret), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    await mkdir(TREASURY_DIR, { recursive: true });
+    const tmpPath = TOTP_FALLBACK_PATH + '.tmp.' + process.pid;
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(Buffer.concat([salt, iv, tag, encrypted]));
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, TOTP_FALLBACK_PATH);
+}
+async function readFromFile(totpPassword) {
+    if (!existsSync(TOTP_FALLBACK_PATH))
+        return null;
+    try {
+        const raw = await readFile(TOTP_FALLBACK_PATH);
+        const salt = raw.subarray(0, 32);
+        const iv = raw.subarray(32, 48);
+        const tag = raw.subarray(48, 64);
+        const ciphertext = raw.subarray(64);
+        const { createDecipheriv, scrypt: scryptCb } = await import('node:crypto');
+        const key = await new Promise((resolve, reject) => {
+            scryptCb(totpPassword.slice(0, 256), salt, 32, { N: 131072, r: 8, p: 1 }, (err, k) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(k);
+            });
+        });
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Public API ────────────────────────────────────────
+/** Set up TOTP — generates secret, stores in keychain, returns URI for QR display */
+export async function totpSetup(fallbackPassword) {
+    const secret = generateSecret();
+    const uri = generateOtpauthUri(secret);
+    const b32 = encodeBase32(secret);
+    // Try keychain first (ADR-4)
+    const keychainOk = await storeInKeychain(secret);
+    if (keychainOk) {
+        return { uri, secret: b32, stored: 'keychain' };
+    }
+    // Fallback to encrypted file
+    if (!fallbackPassword) {
+        throw new Error('System keychain unavailable. Provide a TOTP encryption password (must differ from vault password).');
+    }
+    await storeInFile(secret, fallbackPassword);
+    return { uri, secret: b32, stored: 'file' };
+}
+/** Verify a TOTP code. Returns true if valid, false if invalid or replay. */
+export async function totpVerify(code, fallbackPassword) {
+    // Read secret from keychain or file
+    let secret = await readFromKeychain();
+    if (!secret && fallbackPassword) {
+        secret = await readFromFile(fallbackPassword);
+    }
+    if (!secret) {
+        throw new Error('TOTP not configured. Run /cultivation install or voidforge treasury --setup-2fa.');
+    }
+    const currentStep = getCurrentStep();
+    // Check current step ± window
+    for (let offset = -TOTP_WINDOW; offset <= TOTP_WINDOW; offset++) {
+        const step = currentStep + offset;
+        const expected = generateTotpCode(secret, step);
+        // SEC-003: Use constant-time comparison for TOTP codes
+        const codeMatch = code.length === expected.length &&
+            timingSafeEqual(Buffer.from(code), Buffer.from(expected));
+        if (codeMatch) {
+            // VG-003: Replay protection — reject reuse of ANY code within the window period
+            const codeKey = code + ':' + step;
+            if (session && session.usedCodes.has(codeKey)) {
+                return false; // Replay detected
+            }
+            // Set or update session, tracking all used codes
+            if (!session) {
+                session = { verifiedAt: Date.now(), lastUsedAt: Date.now(), usedCodes: new Set() };
+            }
+            else {
+                session.lastUsedAt = Date.now();
+            }
+            session.usedCodes.add(codeKey);
+            // Prune codes older than 3 TOTP periods (90 seconds)
+            // LOKI-005: If clock jumped (step difference > 10), clear all used codes to prevent lockout
+            const toDelete = [];
+            for (const key of session.usedCodes) {
+                const keyStep = parseInt(key.split(':')[1]);
+                const drift = currentStep - keyStep;
+                if (drift > 3 || drift < -3)
+                    toDelete.push(key);
+            }
+            for (const key of toDelete)
+                session.usedCodes.delete(key);
+            return true;
+        }
+    }
+    return false;
+}
+/** Check if a TOTP session is still valid (5 min TTL, 2 min idle) */
+export function totpSessionValid() {
+    if (!session)
+        return false;
+    const now = Date.now();
+    if (now - session.verifiedAt > TOTP_SESSION_TTL_MS) {
+        session = null;
+        return false;
+    }
+    if (now - session.lastUsedAt > TOTP_IDLE_TTL_MS) {
+        session = null;
+        return false;
+    }
+    session.lastUsedAt = now; // Touch
+    return true;
+}
+/** Invalidate the TOTP session */
+export function totpSessionInvalidate() {
+    session = null;
+}
+/** Check if TOTP is configured (keychain or file) */
+export async function totpIsConfigured(fallbackPassword) {
+    const secret = await readFromKeychain();
+    if (secret)
+        return true;
+    if (fallbackPassword) {
+        const fileSecret = await readFromFile(fallbackPassword);
+        if (fileSecret)
+            return true;
+    }
+    return existsSync(TOTP_FALLBACK_PATH);
+}
+/** Remove TOTP configuration */
+export async function totpRemove() {
+    await deleteFromKeychain();
+    // Don't delete the file — user may want to keep the backup
+    totpSessionInvalidate();
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export { type UserRole, type SessionInfo, 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 type { UserRole } from './tower-session.js';
+export declare function setRemoteMode(enabled: boolean): void;
+export declare function isRemoteMode(): boolean;
+export declare function setLanMode(enabled: boolean): void;
+export declare function isLanMode(): boolean;
+/** Get client IP — delegates to rate-limit module but passes remoteMode state. */
+export declare function getClientIp(req: {
+    headers: Record<string, string | string[] | undefined>;
+    socket: {
+        remoteAddress?: string;
+    };
+}): string;
+export declare function isValidUsername(username: string): boolean;
+export declare function hasUsers(): Promise<boolean>;
+export declare function createUser(username: string, password: string, role?: UserRole): Promise<{
+    totpSecret: string;
+    totpUri: string;
+}>;
+export declare function removeUser(targetUsername: string): Promise<void>;
+export declare function updateUserRole(targetUsername: string, newRole: UserRole): Promise<void>;
+export declare function listUsers(): Promise<Array<{
+    username: string;
+    role: UserRole;
+    createdAt: string;
+}>>;
+export declare function getUserRole(username: string): Promise<UserRole | null>;
+export declare function login(username: string, password: string, totpCode: string, ip: string): Promise<{
+    token: string;
+} | {
+    error: string;
+    retryAfterMs?: number;
+}>;