thevoidforge 21.0.0

package/dist/wizard/lib/treasury-backup.js

@@ -0,0 +1,126 @@
+/**
+ * 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)
+ */
+import { readdir, readFile, mkdir, unlink } from 'node:fs/promises';
+import { createCipheriv, randomBytes, scrypt } from 'node:crypto';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+const TREASURY_DIR = join(homedir(), '.voidforge', 'treasury');
+const BACKUP_DIR = join(homedir(), '.voidforge', 'backups');
+const RETENTION_DAYS = 30;
+/**
+ * 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 async function createDailyBackup(vaultPassword) {
+    const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    const backupPath = join(BACKUP_DIR, `treasury-${date}.backup.enc`);
+    await mkdir(BACKUP_DIR, { recursive: true });
+    // Skip if today's backup already exists
+    if (existsSync(backupPath)) {
+        return { path: backupPath, files: 0 };
+    }
+    // Collect all files from treasury directory
+    const files = [];
+    if (existsSync(TREASURY_DIR)) {
+        await collectFiles(TREASURY_DIR, TREASURY_DIR, files);
+    }
+    if (files.length === 0) {
+        return { path: '', files: 0 };
+    }
+    // Serialize file manifest
+    const manifest = files.map(f => ({
+        path: f.relativePath,
+        size: f.content.length,
+    }));
+    // Create a simple archive format: manifest JSON + file contents
+    const archiveData = Buffer.concat([
+        Buffer.from(JSON.stringify(manifest) + '\n---MANIFEST_END---\n'),
+        ...files.map(f => Buffer.concat([
+            Buffer.from(`---FILE:${f.relativePath}:${f.content.length}---\n`),
+            f.content,
+            Buffer.from('\n'),
+        ])),
+    ]);
+    // Encrypt the archive (§9.19.13: encrypted with vault password)
+    const salt = randomBytes(32);
+    const iv = randomBytes(16);
+    const key = await deriveKey(vaultPassword, salt);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(archiveData), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    // Format: salt (32) + iv (16) + authTag (16) + ciphertext
+    const output = Buffer.concat([salt, iv, authTag, encrypted]);
+    // Write atomically
+    const tmpPath = backupPath + '.tmp';
+    const { writeFile: writeFileAsync, rename: renameAsync } = await import('node:fs/promises');
+    await writeFileAsync(tmpPath, output, { mode: 0o600 });
+    await renameAsync(tmpPath, backupPath);
+    // Prune old backups
+    await pruneOldBackups();
+    return { path: backupPath, files: files.length };
+}
+async function collectFiles(dir, baseDir, result) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await collectFiles(fullPath, baseDir, result);
+        }
+        else if (entry.isFile()) {
+            // v17.0: Size limit to prevent unbounded memory allocation
+            const fileStat = await import('node:fs/promises').then(m => m.stat(fullPath));
+            if (fileStat.size > 100 * 1024 * 1024) {
+                console.warn(`Treasury backup: skipping ${entry.name} (${fileStat.size} bytes > 100MB limit)`);
+                continue;
+            }
+            const relativePath = fullPath.replace(baseDir + '/', '');
+            const content = await readFile(fullPath);
+            result.push({ relativePath, content });
+        }
+    }
+}
+async function deriveKey(password, salt) {
+    return new Promise((resolve, reject) => {
+        scrypt(password.slice(0, 256), salt, 32, { N: 131072, r: 8, p: 1 }, (err, key) => {
+            if (err)
+                reject(err);
+            else
+                resolve(key);
+        });
+    });
+}
+async function pruneOldBackups() {
+    if (!existsSync(BACKUP_DIR))
+        return;
+    const entries = await readdir(BACKUP_DIR);
+    const cutoff = Date.now() - RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    for (const entry of entries) {
+        if (!entry.startsWith('treasury-') || !entry.endsWith('.backup.enc'))
+            continue;
+        const dateStr = entry.replace('treasury-', '').replace('.backup.enc', '');
+        const fileDate = new Date(dateStr).getTime();
+        if (fileDate < cutoff) {
+            await unlink(join(BACKUP_DIR, entry));
+        }
+    }
+}
+/**
+ * Export all financial data (encrypted with vault password).
+ * Used by /treasury --export and uninstall safety.
+ */
+export async function exportTreasuryData(vaultPassword, outputPath) {
+    const result = await createDailyBackup(vaultPassword);
+    if (result.path) {
+        const { copyFile } = await import('node:fs/promises');
+        await copyFile(result.path, outputPath);
+    }
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Treasury Heartbeat — heartbeat jobs, socket handlers, and circuit breakers
+ * for stablecoin funding operations.
+ *
+ * Wires the pure-logic modules (treasury-planner, funding-policy, reconciliation-engine)
+ * into the heartbeat daemon's job scheduler and socket API.
+ *
+ * Only activates when stablecoin funding is configured (funding-config.json.enc exists).
+ *
+ * PRD Reference: S10.4, S12, S13.2, S15, S16
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import type { JobScheduler } from './daemon-core.js';
+/** Logger interface matching heartbeat's createLogger output. */
+interface Logger {
+    log(message: string): void;
+}
+/** Callback to write current daemon state to heartbeat.json. */
+type WriteStateFn = () => Promise<void>;
+/** Callback to trigger a freeze from circuit breaker. */
+type FreezeFn = (reason: string) => Promise<void>;
+interface TreasuryHeartbeatState {
+    stablecoinBalanceCents: number;
+    bankBalanceCents: number;
+    pendingTransferCount: number;
+    lastOfframpAt: string | null;
+    lastReconciliationAt: string | null;
+    runwayDays: number;
+    fundingFrozen: boolean;
+    freezeReason: string | null;
+    consecutiveMismatches: number;
+    consecutiveProviderFailures: number;
+    lastCircuitBreakerCheck: string | null;
+    dailyMovementCents: number;
+    dailyMovementDate: string;
+    /** Pending obligations from billing scans (invoices + expected debits). */
+    pendingObligationsCents: number;
+    /** Google invoice data from last scan. */
+    googleInvoiceDueSoon: boolean;
+    googleInvoiceCents: number;
+    /** Meta debit data from last scan. */
+    metaDebitFailed: boolean;
+    metaPaymentRisk: boolean;
+    metaForecast7DayCents: number;
+}
+export declare function isStablecoinConfigured(): boolean;
+interface PendingTransfer {
+    id: string;
+    fundingPlanId: string;
+    providerTransferId: string;
+    amountCents: number;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+    initiatedAt: string;
+    lastPolledAt: string;
+}
+interface CircuitBreakerResult {
+    shouldFreeze: boolean;
+    reasons: string[];
+}
+export declare function evaluateCircuitBreakers(state: TreasuryHeartbeatState): CircuitBreakerResult;
+/** Evaluate CB-2 specifically for pending transfers beyond SLA. */
+export declare function evaluateTransferSlaBreaker(transfers: PendingTransfer[], slaHours?: number): CircuitBreakerResult;
+/** Evaluate CB-4 and CB-5 from billing adapter state. */
+export declare function evaluateBillingBreakers(opts: {
+    googleInvoiceDueSoon: boolean;
+    googleInvoiceCents: number;
+    bankBalanceCents: number;
+    minimumBufferCents: number;
+    metaDebitFailed: boolean;
+    metaPaymentRisk: boolean;
+}): CircuitBreakerResult;
+export declare function registerTreasuryJobs(scheduler: JobScheduler, logger: Logger, writeCurrentState: WriteStateFn, triggerFreeze: FreezeFn, vaultKey: string | null): void;
+export declare function handleTreasuryRequest(method: string, path: string, _body: unknown, auth: {
+    vaultVerified: boolean;
+    totpVerified: boolean;
+}, logger: Logger, triggerFreeze: FreezeFn, vaultKey: string | null): Promise<{
+    status: number;
+    body: unknown;
+} | null>;
+export declare function executeTreasuryFreeze(reason: string, logger: Logger): Promise<void>;
+export declare function getTreasuryStateSnapshot(): TreasuryHeartbeatState;
+export type { TreasuryHeartbeatState, CircuitBreakerResult, PendingTransfer, Logger, WriteStateFn, FreezeFn, };