voidforge-build 23.9.1

package/dist/wizard/lib/financial/stablecoin/sandbox-stablecoin.js

@@ -0,0 +1,202 @@
+/**
+ * Sandbox Stablecoin Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the StablecoinSetup + StablecoinAdapter
+ * interfaces. Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox provider (No Stubs Doctrine).
+ *
+ * Simulates a USDC wallet with ~$50,000 starting balance, realistic off-ramp
+ * lifecycle (pending -> processing -> completed over 3 polls), and deterministic
+ * fee estimates.
+ */
+import { randomUUID } from 'node:crypto';
+import { toCents, computeTransferHash } from './base.js';
+// ── Setup Implementation ─────────────────────────────
+export class SandboxStablecoinSetup {
+    async authenticate(_credentials) {
+        return {
+            valid: true,
+            accountId: `sandbox_wallet_${randomUUID().slice(0, 8)}`,
+            permissions: ['read_balances', 'initiate_payouts', 'read_payouts'],
+        };
+    }
+    async verifySupportedAssets(_credentials) {
+        return [
+            {
+                asset: 'USDC',
+                network: 'ETH',
+                contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+                minRedemption: toCents(100),
+            },
+            {
+                asset: 'USDC',
+                network: 'SOL',
+                contractAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+                minRedemption: toCents(50),
+            },
+        ];
+    }
+    async verifyLinkedBank(_credentials) {
+        return {
+            linked: true,
+            bankId: 'sandbox_bank_001',
+            bankName: 'Sandbox Mercury Account',
+            accountLast4: '4242',
+        };
+    }
+    async getInitialBalances(_credentials) {
+        return [
+            {
+                provider: 'circle',
+                asset: 'USDC',
+                network: 'ETH',
+                balanceCents: toCents(50_000),
+                lastUpdated: new Date().toISOString(),
+            },
+        ];
+    }
+}
+// ── Runtime Adapter Implementation ───────────────────
+export class SandboxStablecoinAdapter {
+    balanceCents;
+    transfers = new Map();
+    constructor(initialBalanceDollars = 50_000) {
+        this.balanceCents = toCents(initialBalanceDollars);
+    }
+    async getBalances() {
+        const now = new Date().toISOString();
+        const stablecoin = [
+            {
+                provider: 'circle',
+                asset: 'USDC',
+                network: 'ETH',
+                balanceCents: this.balanceCents,
+                lastUpdated: now,
+            },
+        ];
+        return {
+            stablecoin,
+            fiat: [],
+            totalStablecoinCents: this.balanceCents,
+            totalFiatAvailableCents: 0,
+        };
+    }
+    async quoteRedemption(amountCents) {
+        // Sandbox fee: flat $10 per off-ramp
+        const feeCents = toCents(10);
+        return {
+            provider: 'circle',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            requestedCents: amountCents,
+            estimatedFeeCents: feeCents,
+            estimatedNetCents: (amountCents - feeCents),
+            estimatedSettlementMinutes: 60,
+            expiresAt: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
+        };
+    }
+    async initiateOfframp(plan, previousHash) {
+        const feeCents = toCents(10);
+        const netCents = (plan.requiredCents - feeCents);
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const providerTransferId = `sandbox_xfer_${randomUUID().slice(0, 12)}`;
+        // Deduct from simulated balance
+        this.balanceCents = (this.balanceCents - plan.requiredCents);
+        const record = {
+            id,
+            fundingPlanId: plan.id,
+            providerTransferId,
+            provider: 'circle',
+            direction: 'crypto_to_fiat',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            amountCents: plan.requiredCents,
+            feesCents: feeCents,
+            netAmountCents: netCents,
+            destinationBankId: plan.destinationBankId,
+            status: 'pending',
+            initiatedAt: now,
+            idempotencyKey: plan.idempotencyKey,
+            previousHash,
+        };
+        const hash = computeTransferHash(record, previousHash);
+        const fullRecord = { ...record, hash };
+        this.transfers.set(id, { record: fullRecord, pollCount: 0 });
+        return fullRecord;
+    }
+    async getTransferStatus(transferId) {
+        const state = this.transfers.get(transferId);
+        if (!state) {
+            // Return failed status for unknown IDs — unknown transfers should not
+            // be reported as completed (could cause false settlement in reconciliation).
+            return {
+                transferId,
+                providerTransferId: 'unknown',
+                status: 'failed',
+                amountCents: 0,
+                feesCents: 0,
+                initiatedAt: new Date().toISOString(),
+                providerRawStatus: 'not_found',
+            };
+        }
+        // Simulate lifecycle: pending (poll 0) -> processing (poll 1) -> completed (poll 2+)
+        state.pollCount += 1;
+        let status;
+        let rawStatus;
+        let completedAt;
+        if (state.pollCount <= 1) {
+            status = 'pending';
+            rawStatus = 'pending';
+        }
+        else if (state.pollCount === 2) {
+            status = 'processing';
+            rawStatus = 'processing';
+        }
+        else {
+            status = 'completed';
+            rawStatus = 'complete';
+            completedAt = new Date().toISOString();
+            // Update stored record status
+            state.record = { ...state.record, status: 'completed', completedAt };
+        }
+        return {
+            transferId: state.record.id,
+            providerTransferId: state.record.providerTransferId,
+            status,
+            amountCents: state.record.amountCents,
+            feesCents: state.record.feesCents,
+            initiatedAt: state.record.initiatedAt,
+            completedAt,
+            estimatedCompletionAt: status !== 'completed'
+                ? new Date(Date.now() + 60 * 60 * 1000).toISOString()
+                : undefined,
+            providerRawStatus: rawStatus,
+        };
+    }
+    async cancelTransfer(transferId) {
+        const state = this.transfers.get(transferId);
+        if (!state) {
+            return { cancelled: false, reason: 'Transfer not found' };
+        }
+        if (state.record.status === 'completed') {
+            return { cancelled: false, reason: 'Transfer already completed' };
+        }
+        if (state.record.status === 'processing') {
+            return { cancelled: false, reason: 'Transfer is processing — cannot cancel' };
+        }
+        // Refund the balance and mark cancelled
+        this.balanceCents = (this.balanceCents + state.record.amountCents);
+        state.record = { ...state.record, status: 'cancelled' };
+        return { cancelled: true };
+    }
+    async listCompletedTransfers(_dateRange) {
+        const completed = [];
+        for (const state of this.transfers.values()) {
+            if (state.record.status === 'completed') {
+                completed.push(state.record);
+            }
+        }
+        return completed;
+    }
+}

package/dist/wizard/lib/financial/treasury-planner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Treasury Planner — pure logic module for runway forecasting and plan generation.
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * All monetary values use branded integer cents (Cents type).
+ *
+ * PRD Reference: §12.4 (FundingPlan), §12.5 (TransferRecord), §15 (Rules Engine)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import type { Cents, FundingPlan, OperatingBankAccount, StablecoinFundingSource, PendingObligation } from '../patterns/funding-plan.js';
+interface CampaignSpendProjection {
+    campaignId: string;
+    platform: 'google' | 'meta';
+    dailyBudgetCents: Cents;
+    status: 'active' | 'paused';
+}
+interface FundingPlanConfig {
+    /** Minimum off-ramp amount (provider-enforced) */
+    minimumOfframpCents: Cents;
+    /** Target buffer above minimum — the "comfort zone" */
+    bufferTargetCents: Cents;
+    /** Maximum single off-ramp amount per day */
+    maxDailyOfframpCents: Cents;
+    /** Days of runway to maintain as target */
+    targetRunwayDays: number;
+}
+interface OfframpDecision {
+    shouldOfframp: boolean;
+    reason: string;
+    amountCents: Cents;
+}
+interface ObligationInput {
+    id: string;
+    platform: 'google' | 'meta';
+    type: 'invoice' | 'debit' | 'buffer';
+    amountCents: Cents;
+    dueDate: string;
+    overdue: boolean;
+}
+export declare function calculateRunway(bankBalanceCents: Cents, dailySpendRateCents: Cents): number;
+export declare function forecastSpend(campaigns: CampaignSpendProjection[], days: number): Cents;
+export declare function shouldTriggerOfframp(bankBalanceCents: Cents, bufferThresholdCents: Cents, pendingSpendCents: Cents): OfframpDecision;
+export declare function calculateRequiredOfframp(bankBalanceCents: Cents, bufferTargetCents: Cents, pendingObligationsCents: Cents, feeEstimateCents: Cents): Cents;
+export declare function prioritizeAllObligations(invoices: ObligationInput[], debits: ObligationInput[], bufferNeeds: ObligationInput[]): PendingObligation[];
+export declare function generateFundingPlan(source: StablecoinFundingSource, bank: OperatingBankAccount, obligations: ObligationInput[], config: FundingPlanConfig, previousHash: string): FundingPlan | null;
+export declare function calculateDailySpendRate(campaigns: CampaignSpendProjection[]): Cents;
+export declare function forecastRunway(bankBalanceCents: Cents, campaigns: CampaignSpendProjection[], pendingObligationsCents: Cents): {
+    runwayDays: number;
+    dailySpendCents: Cents;
+    effectiveBalanceCents: Cents;
+};
+export type { CampaignSpendProjection, FundingPlanConfig, OfframpDecision, ObligationInput, };

package/dist/wizard/lib/financial/treasury-planner.js

@@ -0,0 +1,128 @@
+/**
+ * Treasury Planner — pure logic module for runway forecasting and plan generation.
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * All monetary values use branded integer cents (Cents type).
+ *
+ * PRD Reference: §12.4 (FundingPlan), §12.5 (TransferRecord), §15 (Rules Engine)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import { toCents, createFundingPlan, prioritizeObligations, } from '../patterns/funding-plan.js';
+// ── Runway Calculation ───────────────────────────────
+// Returns the number of days the current bank balance can sustain spend.
+export function calculateRunway(bankBalanceCents, dailySpendRateCents) {
+    if (dailySpendRateCents <= 0)
+        return Infinity;
+    return Math.floor(bankBalanceCents / dailySpendRateCents);
+}
+// ── Spend Forecast ───────────────────────────────────
+// Projects total spend over N days based on active campaign budgets.
+export function forecastSpend(campaigns, days) {
+    if (days <= 0)
+        return 0;
+    const dailyTotal = campaigns
+        .filter(c => c.status === 'active')
+        .reduce((sum, c) => sum + c.dailyBudgetCents, 0);
+    return Math.round(dailyTotal * days);
+}
+// ── Off-ramp Trigger Decision ────────────────────────
+// Determines whether an off-ramp should be triggered and why.
+export function shouldTriggerOfframp(bankBalanceCents, bufferThresholdCents, pendingSpendCents) {
+    const effectiveBalance = (bankBalanceCents - pendingSpendCents);
+    if (effectiveBalance < bufferThresholdCents) {
+        const deficit = (bufferThresholdCents - effectiveBalance);
+        return {
+            shouldOfframp: true,
+            reason: `Effective balance $${(effectiveBalance / 100).toFixed(2)} below buffer threshold $${(bufferThresholdCents / 100).toFixed(2)} — deficit $${(deficit / 100).toFixed(2)}`,
+            amountCents: deficit,
+        };
+    }
+    return {
+        shouldOfframp: false,
+        reason: `Effective balance $${(effectiveBalance / 100).toFixed(2)} above buffer threshold $${(bufferThresholdCents / 100).toFixed(2)}`,
+        amountCents: 0,
+    };
+}
+// ── Required Off-ramp Amount ─────────────────────────
+// Calculates the exact off-ramp amount needed, clamped to provider constraints.
+export function calculateRequiredOfframp(bankBalanceCents, bufferTargetCents, pendingObligationsCents, feeEstimateCents) {
+    // How much fiat we need: buffer + obligations + fees - current balance
+    const required = (bufferTargetCents + pendingObligationsCents + feeEstimateCents - bankBalanceCents);
+    if (required <= 0)
+        return 0;
+    return required;
+}
+// ── Obligation Prioritization ────────────────────────
+// Sorts obligations by urgency: overdue first, then by due date.
+export function prioritizeAllObligations(invoices, debits, bufferNeeds) {
+    const all = [...invoices, ...debits, ...bufferNeeds].map(o => ({
+        id: o.id,
+        platform: o.platform,
+        amountCents: o.amountCents,
+        dueDate: o.dueDate,
+        overdue: o.overdue,
+    }));
+    return prioritizeObligations(all);
+}
+// ── Funding Plan Generation ──────────────────────────
+// Creates a FundingPlan based on current treasury state and obligations.
+export function generateFundingPlan(source, bank, obligations, config, previousHash) {
+    // Sum all pending obligation amounts
+    const totalObligationsCents = obligations.reduce((sum, o) => sum + o.amountCents, 0);
+    // Calculate how much additional fiat we need
+    const requiredCents = calculateRequiredOfframp(bank.availableBalanceCents, config.bufferTargetCents, totalObligationsCents, toCents(10));
+    // No funding needed
+    if (requiredCents <= 0)
+        return null;
+    // Clamp to maximum daily off-ramp
+    const clampedCents = Math.min(requiredCents, config.maxDailyOfframpCents);
+    // Enforce minimum off-ramp amount
+    if (clampedCents < config.minimumOfframpCents) {
+        // If the required amount is below provider minimum but > 0, round up to minimum
+        const finalCents = config.minimumOfframpCents;
+        return createFundingPlan(determineFundingReason(obligations, bank), source.id, bank.id, determinePlatformTarget(obligations), finalCents, previousHash);
+    }
+    return createFundingPlan(determineFundingReason(obligations, bank), source.id, bank.id, determinePlatformTarget(obligations), clampedCents, previousHash);
+}
+// ── Daily Spend Rate ─────────────────────────────────
+// Calculates the average daily spend rate from active campaigns.
+export function calculateDailySpendRate(campaigns) {
+    return campaigns
+        .filter(c => c.status === 'active')
+        .reduce((sum, c) => (sum + c.dailyBudgetCents), 0);
+}
+// ── Runway Forecast ──────────────────────────────────
+// Combines balance, spend rate, and pending obligations into a runway projection.
+export function forecastRunway(bankBalanceCents, campaigns, pendingObligationsCents) {
+    const dailySpendCents = calculateDailySpendRate(campaigns);
+    const effectiveBalanceCents = (bankBalanceCents - pendingObligationsCents);
+    const runwayDays = calculateRunway(Math.max(effectiveBalanceCents, 0), dailySpendCents);
+    return { runwayDays, dailySpendCents, effectiveBalanceCents };
+}
+// ── Private Helpers ──────────────────────────────────
+function determineFundingReason(obligations, bank) {
+    // Check for overdue invoices first
+    const hasOverdue = obligations.some(o => o.overdue);
+    if (hasOverdue)
+        return 'INVOICE_DUE';
+    // Check for upcoming invoices within 7 days
+    const sevenDaysOut = Date.now() + 7 * 24 * 60 * 60 * 1000;
+    const hasUpcoming = obligations.some(o => o.type === 'invoice' && new Date(o.dueDate).getTime() <= sevenDaysOut);
+    if (hasUpcoming)
+        return 'INVOICE_DUE';
+    // Check if bank is below minimum buffer
+    if (bank.availableBalanceCents < bank.minimumBufferCents)
+        return 'LOW_BUFFER';
+    // Default: runway shortfall
+    return 'RUNWAY_SHORTFALL';
+}
+function determinePlatformTarget(obligations) {
+    // If all obligations are for one platform, target that platform
+    const platforms = new Set(obligations.map(o => o.platform));
+    if (platforms.size === 1) {
+        const platform = [...platforms][0];
+        return platform;
+    }
+    // Mixed or no obligations: shared buffer
+    return 'shared_buffer';
+}

package/dist/wizard/lib/financial-core.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Financial core — re-exports from the financial-transaction pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { atomicWrite, appendToLog, idempotentAppend, toCents, toDollars, formatCurrency, formatRoas, formatPercentage, SPEND_LOG, REVENUE_LOG, TREASURY_DIR, getTreasuryDir, getSpendLog, getRevenueLog, getPendingOps, getBudgetsFile } from './patterns/financial-transaction.js';
+export type { Cents, ReconciliationReport, Transaction, Budget, GrowthCampaign, RevenueEvent } from './patterns/financial-transaction.js';

package/dist/wizard/lib/financial-core.js

@@ -0,0 +1,5 @@
+/**
+ * Financial core — re-exports from the financial-transaction pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { atomicWrite, appendToLog, idempotentAppend, toCents, toDollars, formatCurrency, formatRoas, formatPercentage, SPEND_LOG, REVENUE_LOG, TREASURY_DIR, getTreasuryDir, getSpendLog, getRevenueLog, getPendingOps, getBudgetsFile } from './patterns/financial-transaction.js';

package/dist/wizard/lib/financial-vault.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Financial Vault — Separate encrypted storage for ad platform and bank credentials.
+ *
+ * Key differences from the infrastructure vault (vault.ts):
+ * - Stored at ~/.voidforge/treasury/vault.enc (not ~/.voidforge/vault.enc)
+ * - Uses scrypt key derivation (memory-hard, unlike PBKDF2 in the infra vault)
+ *   Note: PRD specifies Argon2id but Node.js has no built-in Argon2id.
+ *   scrypt is the closest built-in memory-hard KDF. Zero-dependency constraint wins.
+ * - Separate password from the infrastructure vault
+ * - TOTP 2FA required for write operations (see totp.ts)
+ *
+ * PRD Reference: §9.11 (Financial Security), ADR-4 (TOTP storage), §9.18 (macOS fsync)
+ *
+ * Threat model: compromise of the infrastructure vault should NOT automatically
+ * compromise the financial vault. Different password, different file, different KDF.
+ */
+/** Store a financial credential */
+export declare function financialVaultSet(password: string, key: string, value: string): Promise<void>;
+/** Retrieve a financial credential */
+export declare function financialVaultGet(password: string, key: string): Promise<string | null>;
+/** Delete a financial credential */
+export declare function financialVaultDelete(password: string, key: string): Promise<void>;
+/** Check if the financial vault exists */
+export declare function financialVaultExists(): boolean;
+/** Verify password can decrypt the vault */
+export declare function financialVaultUnlock(password: string): Promise<boolean>;
+/** List stored keys (requires password) */
+export declare function financialVaultKeys(password: string): Promise<string[]>;
+/** Zero the in-memory cache — call on SIGTERM, vault timeout, or manual lock */
+export declare function financialVaultLock(): void;
+/** Return the vault file path */
+export declare function financialVaultPath(): string;
+/** Return the treasury directory path */
+export declare function treasuryDir(): string;

package/dist/wizard/lib/financial-vault.js

@@ -0,0 +1,200 @@
+/**
+ * Financial Vault — Separate encrypted storage for ad platform and bank credentials.
+ *
+ * Key differences from the infrastructure vault (vault.ts):
+ * - Stored at ~/.voidforge/treasury/vault.enc (not ~/.voidforge/vault.enc)
+ * - Uses scrypt key derivation (memory-hard, unlike PBKDF2 in the infra vault)
+ *   Note: PRD specifies Argon2id but Node.js has no built-in Argon2id.
+ *   scrypt is the closest built-in memory-hard KDF. Zero-dependency constraint wins.
+ * - Separate password from the infrastructure vault
+ * - TOTP 2FA required for write operations (see totp.ts)
+ *
+ * PRD Reference: §9.11 (Financial Security), ADR-4 (TOTP storage), §9.18 (macOS fsync)
+ *
+ * Threat model: compromise of the infrastructure vault should NOT automatically
+ * compromise the financial vault. Different password, different file, different KDF.
+ */
+import { createCipheriv, createDecipheriv, scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFile, mkdir, open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { platform } from 'node:os';
+import { TREASURY_DIR } from './financial-core.js';
+// Vault stays global (user-scoped credentials, ADR-040 §4)
+const VAULT_PATH = join(TREASURY_DIR, 'vault.enc');
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32;
+const IV_LENGTH = 16;
+const SALT_LENGTH = 32;
+const AUTH_TAG_LENGTH = 16;
+const MAX_PASSWORD_LENGTH = 256;
+// scrypt parameters — memory-hard to resist brute force
+// N=2^17 (131072), r=8, p=1 — ~128MB memory, ~1s on modern hardware
+const SCRYPT_N = 131072;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+/** In-memory cache — zeroed on lock or vault timeout */
+let sessionCache = null;
+/** Write queue to serialize vault operations */
+let writeQueue = Promise.resolve();
+function serialized(fn) {
+    const result = writeQueue.then(fn, () => fn());
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+async function deriveKey(password, salt) {
+    const capped = password.slice(0, MAX_PASSWORD_LENGTH);
+    return new Promise((resolve, reject) => {
+        scrypt(capped, salt, KEY_LENGTH, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P }, (err, key) => {
+            if (err)
+                reject(err);
+            else
+                resolve(key);
+        });
+    });
+}
+async function encrypt(plaintext, password) {
+    const salt = randomBytes(SALT_LENGTH);
+    const iv = randomBytes(IV_LENGTH);
+    const key = await deriveKey(password, salt);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    // Format: salt (32) + iv (16) + authTag (16) + ciphertext
+    return Buffer.concat([salt, iv, authTag, encrypted]);
+}
+async function decrypt(data, password) {
+    if (data.length < SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH + 1) {
+        throw new Error('Financial vault data is corrupted or empty');
+    }
+    const salt = data.subarray(0, SALT_LENGTH);
+    const iv = data.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
+    const authTag = data.subarray(SALT_LENGTH + IV_LENGTH, SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = data.subarray(SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
+    const key = await deriveKey(password, salt);
+    const decipher = createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString('utf-8');
+}
+async function readVault(password) {
+    if (sessionCache) {
+        const a = Buffer.from(sessionCache.password, 'utf-8');
+        const b = Buffer.from(password, 'utf-8');
+        if (a.length === b.length && timingSafeEqual(a, b)) {
+            return { ...sessionCache.data }; // Return copy to prevent mutation
+        }
+    }
+    if (!existsSync(VAULT_PATH)) {
+        return {};
+    }
+    const raw = await readFile(VAULT_PATH);
+    const json = await decrypt(raw, password);
+    const data = JSON.parse(json);
+    sessionCache = { password, data };
+    return { ...data };
+}
+async function writeVault(password, data) {
+    await mkdir(TREASURY_DIR, { recursive: true });
+    const json = JSON.stringify(data);
+    const encrypted = await encrypt(json, password);
+    // Atomic write: temp → fsync → rename (per ADR-1)
+    const tmpPath = VAULT_PATH + '.tmp.' + process.pid;
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(encrypted);
+        // macOS: fsync() doesn't guarantee physical durability (§9.18)
+        // F_FULLFSYNC (fcntl flag 51) is required for financial files
+        // Node.js datasync is the closest built-in; document the gap
+        if (platform() === 'darwin') {
+            await fh.datasync();
+        }
+        else {
+            await fh.sync();
+        }
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, VAULT_PATH);
+    sessionCache = { password, data: { ...data } };
+}
+// ── Public API ────────────────────────────────────────
+const MIN_PASSWORD_LENGTH = 12;
+function validatePassword(password) {
+    if (password.length < MIN_PASSWORD_LENGTH) {
+        throw new Error(`Financial vault password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+    }
+}
+/** Store a financial credential */
+export function financialVaultSet(password, key, value) {
+    validatePassword(password);
+    return serialized(async () => {
+        const data = await readVault(password);
+        data[key] = value;
+        await writeVault(password, data);
+    });
+}
+/** Retrieve a financial credential */
+export function financialVaultGet(password, key) {
+    return serialized(async () => {
+        const data = await readVault(password);
+        return data[key] ?? null;
+    });
+}
+/** Delete a financial credential */
+export function financialVaultDelete(password, key) {
+    return serialized(async () => {
+        const data = await readVault(password);
+        delete data[key];
+        await writeVault(password, data);
+    });
+}
+/** Check if the financial vault exists */
+export function financialVaultExists() {
+    return existsSync(VAULT_PATH);
+}
+/** Verify password can decrypt the vault */
+export function financialVaultUnlock(password) {
+    if (!existsSync(VAULT_PATH)) {
+        return Promise.resolve(true); // No vault yet = password is for creation
+    }
+    return serialized(async () => {
+        try {
+            await readVault(password);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** List stored keys (requires password) */
+export function financialVaultKeys(password) {
+    return serialized(async () => {
+        const data = await readVault(password);
+        return Object.keys(data);
+    });
+}
+/** Zero the in-memory cache — call on SIGTERM, vault timeout, or manual lock */
+export function financialVaultLock() {
+    if (sessionCache) {
+        // Best-effort memory zeroing — V8 doesn't guarantee this but it's defense in depth
+        sessionCache.password = '\0'.repeat(sessionCache.password.length);
+        sessionCache = null;
+    }
+    // VG-004: Also invalidate TOTP session when vault is locked
+    try {
+        // Dynamic import to avoid circular dependency — totp.ts is a sibling module
+        import('./totp.js').then(m => m.totpSessionInvalidate()).catch(() => { });
+    }
+    catch { /* totp module may not be loaded */ }
+}
+/** Return the vault file path */
+export function financialVaultPath() {
+    return VAULT_PATH;
+}
+/** Return the treasury directory path */
+export function treasuryDir() {
+    return TREASURY_DIR;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Minimal YAML frontmatter parser for PRD documents.
+ * Handles the simple key: value format used in PRD frontmatter blocks.
+ */
+export interface PrdFrontmatter {
+    name?: string;
+    type?: string;
+    framework?: string;
+    database?: string;
+    cache?: string;
+    styling?: string;
+    auth?: string;
+    payments?: string;
+    workers?: string;
+    admin?: string;
+    marketing?: string;
+    email?: string;
+    deploy?: string;
+    instance_type?: string;
+    hostname?: string;
+    language?: string;
+    description?: string;
+    [key: string]: string | undefined;
+}
+export declare function parseFrontmatter(content: string): {
+    frontmatter: PrdFrontmatter;
+    body: string;
+};
+export declare function generateFrontmatterBlock(fm: PrdFrontmatter): string;
+export declare function validateFrontmatter(fm: PrdFrontmatter): string[];