@nestpilot/mcp-app 1.0.0

package/dist/src/local/local-plan-store.d.ts

@@ -0,0 +1,66 @@
+import type { EncryptionService } from "./encryption.js";
+export interface LocalPlan {
+    id: string;
+    version: number;
+    created: string;
+    updated: string;
+    plan: Record<string, unknown>;
+    forecasts: Record<string, unknown>[];
+    scenarios: Record<string, unknown>[];
+    metadata: {
+        source: "local" | "imported" | "cloud-sync";
+        encryptionVersion: number;
+    };
+}
+export interface PlanSummary {
+    id: string;
+    updated: string;
+    summary: string;
+}
+export declare class LocalPlanStore {
+    private dataDir;
+    private encryption;
+    private plansPath;
+    private forecastsPath;
+    private scenariosPath;
+    constructor(dataDir: string, encryption: EncryptionService);
+    /**
+     * Ensures the data directory structure exists.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates a new plan and persists it encrypted to disk.
+     */
+    create(plan: Record<string, unknown>): Promise<LocalPlan>;
+    /**
+     * Lists all stored plans with summary information.
+     */
+    list(): Promise<PlanSummary[]>;
+    /**
+     * Retrieves a specific plan by ID.
+     */
+    get(planId: string): Promise<LocalPlan>;
+    /**
+     * Updates an existing plan.
+     */
+    save(planId: string, plan: Record<string, unknown>): Promise<LocalPlan>;
+    /**
+     * Deletes a plan and its associated cached data.
+     */
+    delete(planId: string): Promise<void>;
+    /**
+     * Caches a forecast result for offline access.
+     */
+    cacheForecast(planId: string, forecast: Record<string, unknown>): Promise<void>;
+    /**
+     * Retrieves a cached forecast result, or null if none exists.
+     */
+    getCachedForecast(planId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Caches a scenario result.
+     */
+    cacheScenario(planId: string, label: string, scenario: Record<string, unknown>): Promise<void>;
+    private writePlan;
+    private readPlanFile;
+    private buildSummary;
+}

package/dist/src/local/local-plan-store.js

@@ -0,0 +1,195 @@
+/**
+ * Local Plan Store — encrypted file-based CRUD for retirement plans.
+ *
+ * All plan data lives under `~/.nestpilot/plans/{uuid}.json` and is
+ * encrypted at rest using AES-256-GCM. Forecast results are cached
+ * under `~/.nestpilot/forecasts/{uuid}.json` for offline access.
+ *
+ * This module is only active when NESTPILOT_MODE=local.
+ *
+ * @feature FEAT-0087
+ */
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { forecastsDir, plansDir, scenariosDir } from "./local-config.js";
+// ── LocalPlanStore ───────────────────────────────────────────────────────
+export class LocalPlanStore {
+    dataDir;
+    encryption;
+    plansPath;
+    forecastsPath;
+    scenariosPath;
+    constructor(dataDir, encryption) {
+        this.dataDir = dataDir;
+        this.encryption = encryption;
+        this.plansPath = plansDir(dataDir);
+        this.forecastsPath = forecastsDir(dataDir);
+        this.scenariosPath = scenariosDir(dataDir);
+    }
+    /**
+     * Ensures the data directory structure exists.
+     */
+    async initialize() {
+        await fs.mkdir(this.plansPath, { recursive: true });
+        await fs.mkdir(this.forecastsPath, { recursive: true });
+        await fs.mkdir(this.scenariosPath, { recursive: true });
+    }
+    /**
+     * Creates a new plan and persists it encrypted to disk.
+     */
+    async create(plan) {
+        const now = new Date().toISOString();
+        const localPlan = {
+            id: randomUUID(),
+            version: 1,
+            created: now,
+            updated: now,
+            plan,
+            forecasts: [],
+            scenarios: [],
+            metadata: {
+                source: "local",
+                encryptionVersion: 1,
+            },
+        };
+        await this.writePlan(localPlan);
+        return localPlan;
+    }
+    /**
+     * Lists all stored plans with summary information.
+     */
+    async list() {
+        await this.initialize();
+        const files = await fs.readdir(this.plansPath);
+        const summaries = [];
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            try {
+                const localPlan = await this.readPlanFile(path.join(this.plansPath, file));
+                summaries.push({
+                    id: localPlan.id,
+                    updated: localPlan.updated,
+                    summary: this.buildSummary(localPlan),
+                });
+            }
+            catch (e) {
+                console.warn(`[local-plan-store] Skipping corrupt plan file: ${file}`, e);
+            }
+        }
+        return summaries.sort((a, b) => new Date(b.updated).getTime() - new Date(a.updated).getTime());
+    }
+    /**
+     * Retrieves a specific plan by ID.
+     */
+    async get(planId) {
+        const filePath = path.join(this.plansPath, `${planId}.json`);
+        try {
+            return await this.readPlanFile(filePath);
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                throw new Error(`Plan not found: ${planId}`);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Updates an existing plan.
+     */
+    async save(planId, plan) {
+        const existing = await this.get(planId);
+        const updated = {
+            ...existing,
+            plan,
+            version: existing.version + 1,
+            updated: new Date().toISOString(),
+        };
+        await this.writePlan(updated);
+        return updated;
+    }
+    /**
+     * Deletes a plan and its associated cached data.
+     */
+    async delete(planId) {
+        const planFile = path.join(this.plansPath, `${planId}.json`);
+        const forecastFile = path.join(this.forecastsPath, `${planId}.json`);
+        const scenarioFile = path.join(this.scenariosPath, `${planId}.json`);
+        // Remove plan (required)
+        await fs.unlink(planFile).catch((e) => {
+            if (e.code !== "ENOENT")
+                throw e;
+        });
+        // Remove cached data (optional — may not exist)
+        await fs.unlink(forecastFile).catch(() => { });
+        await fs.unlink(scenarioFile).catch(() => { });
+    }
+    /**
+     * Caches a forecast result for offline access.
+     */
+    async cacheForecast(planId, forecast) {
+        const data = JSON.stringify({
+            planId,
+            cached: new Date().toISOString(),
+            forecast,
+        });
+        const encrypted = await this.encryption.encrypt(data);
+        await fs.mkdir(this.forecastsPath, { recursive: true });
+        await fs.writeFile(path.join(this.forecastsPath, `${planId}.json`), encrypted);
+    }
+    /**
+     * Retrieves a cached forecast result, or null if none exists.
+     */
+    async getCachedForecast(planId) {
+        try {
+            const encrypted = await fs.readFile(path.join(this.forecastsPath, `${planId}.json`));
+            const decrypted = await this.encryption.decrypt(encrypted);
+            const data = JSON.parse(decrypted);
+            return data.forecast;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Caches a scenario result.
+     */
+    async cacheScenario(planId, label, scenario) {
+        // Read existing scenarios for this plan
+        let existing = [];
+        try {
+            const encrypted = await fs.readFile(path.join(this.scenariosPath, `${planId}.json`));
+            const decrypted = await this.encryption.decrypt(encrypted);
+            existing = JSON.parse(decrypted);
+        }
+        catch {
+            // No existing scenarios
+        }
+        existing.push({ label, scenario });
+        const data = JSON.stringify(existing);
+        const encrypted = await this.encryption.encrypt(data);
+        await fs.mkdir(this.scenariosPath, { recursive: true });
+        await fs.writeFile(path.join(this.scenariosPath, `${planId}.json`), encrypted);
+    }
+    // ── Internal ──────────────────────────────────────────────────────────
+    async writePlan(localPlan) {
+        await this.initialize();
+        const data = JSON.stringify(localPlan, null, 2);
+        const encrypted = await this.encryption.encrypt(data);
+        await fs.writeFile(path.join(this.plansPath, `${localPlan.id}.json`), encrypted);
+    }
+    async readPlanFile(filePath) {
+        const encrypted = await fs.readFile(filePath);
+        const decrypted = await this.encryption.decrypt(encrypted);
+        return JSON.parse(decrypted);
+    }
+    buildSummary(plan) {
+        const p = plan.plan;
+        const age = p.currentAge ?? p.age ?? "?";
+        const retireAge = p.retirementAge ?? p.retireAge ?? "?";
+        const spending = p.targetMonthlySpending ?? "?";
+        const accountCount = Array.isArray(p.accounts) ? p.accounts.length : 0;
+        return `Age ${age}, retire at ${retireAge}, $${spending}/mo spending, ${accountCount} account(s)`;
+    }
+}

package/dist/src/local/pii-scrubber.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PII Scrubber — strips personally identifiable information from plan
+ * payloads before they are sent to the NestPilot cloud compute API.
+ *
+ * The cloud only needs mathematical inputs (ages, dollar amounts, rates,
+ * account types). It never sees names, notes, labels, account numbers,
+ * institution names, Plaid tokens, email addresses, SSNs, etc.
+ *
+ * @feature FEAT-0087
+ */
+export interface ScrubResult {
+    /** PII-free payload safe for cloud transmission. */
+    payload: Record<string, unknown>;
+    /** Fields that were removed during scrubbing. */
+    removedFields: string[];
+}
+/**
+ * Scrubs PII from a plan payload, keeping only the mathematical fields
+ * required for cloud compute.
+ */
+export declare function scrubPII(plan: Record<string, unknown>): ScrubResult;
+/**
+ * Deep-scans a payload to ensure no PII has leaked through.
+ * Returns `true` if the payload is PII-free.
+ */
+export declare function validateNoPII(payload: Record<string, unknown>): boolean;

package/dist/src/local/pii-scrubber.js

@@ -0,0 +1,219 @@
+/**
+ * PII Scrubber — strips personally identifiable information from plan
+ * payloads before they are sent to the NestPilot cloud compute API.
+ *
+ * The cloud only needs mathematical inputs (ages, dollar amounts, rates,
+ * account types). It never sees names, notes, labels, account numbers,
+ * institution names, Plaid tokens, email addresses, SSNs, etc.
+ *
+ * @feature FEAT-0087
+ */
+// ── Allowed field sets ───────────────────────────────────────────────────
+/** Top-level scalar/numeric fields safe for cloud compute. */
+const ALLOWED_TOP_LEVEL = new Set([
+    "currentAge",
+    "retirementAge",
+    "horizonAge",
+    "targetMonthlySpending",
+    "socialSecurityFRA",
+    "socialSecurityClaimAge",
+    "safeWithdrawalRate",
+    "effectiveTaxRate",
+    "inflationRate",
+    "displayMode",
+    "withdrawalStrategy",
+    "filingStatus",
+    "planId",
+    "schemaVersion",
+    // Nested objects that get scrubbed recursively
+    "accounts",
+    "incomeStreams",
+    "spouse",
+    "socialSecurity",
+    "healthComponents",
+    "spendStreams",
+    "strategy",
+    "assumptions",
+    "goals",
+    "household",
+    "taxProfile",
+    // Scenario-specific
+    "plan",
+    "overrides",
+    "label",
+    "payload",
+]);
+/** Account object fields safe for cloud compute. */
+const ALLOWED_ACCOUNT_FIELDS = new Set([
+    "type",
+    "balance",
+    "annualContribution",
+    "realReturn",
+    "employerMatch",
+    "employerMatchLimit",
+    "enabled",
+    "id",
+]);
+/** Income stream fields safe for cloud compute. */
+const ALLOWED_INCOME_FIELDS = new Set([
+    "type",
+    "amountMonthly",
+    "startAge",
+    "endAge",
+    "enabled",
+    "id",
+    "cola",
+]);
+/** Spouse object fields safe for cloud compute. */
+const ALLOWED_SPOUSE_FIELDS = new Set([
+    "age",
+    "retireAge",
+    "currentAge",
+    "retirementAge",
+    "salary",
+    "socialSecurity",
+    "accounts",
+    "incomeStreams",
+]);
+/** Social Security fields safe for cloud compute. */
+const ALLOWED_SS_FIELDS = new Set([
+    "fraBenefitMonthly",
+    "claimAge",
+    "enabled",
+]);
+/** Known enum values — kept as-is during validation. */
+const KNOWN_ENUM_VALUES = new Set([
+    // Account types
+    "traditional",
+    "roth",
+    "taxable",
+    "hsa",
+    "cash",
+    // Income types
+    "salary",
+    "social_security",
+    "pension",
+    "annuity",
+    "rental",
+    "other",
+    // Filing status
+    "single",
+    "married_filing_jointly",
+    "married_filing_separately",
+    "head_of_household",
+    // Withdrawal strategy
+    "taxable_first",
+    "traditional_first",
+    // Display mode
+    "real",
+    "nominal",
+    // Stress test
+    "EQUITY",
+    "ALL",
+    "PLAN_START",
+    "RETIREMENT",
+    "CUSTOM_YEAR",
+    "2008_CRISIS",
+    "1929_CRASH",
+    "DOT_COM_BUST",
+]);
+// ── PII pattern detection ────────────────────────────────────────────────
+const PII_PATTERNS = [
+    /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, // email
+    /\b\d{3}-\d{2}-\d{4}\b/, // SSN
+    /\b\d{3}\.\d{2}\.\d{4}\b/, // SSN variant
+    /\(\d{3}\)\s?\d{3}-\d{4}/, // phone (xxx) xxx-xxxx
+    /\b\d{3}-\d{3}-\d{4}\b/, // phone xxx-xxx-xxxx
+    /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/, // credit card
+    /\b\d{9,17}\b/, // account numbers (9-17 digits)
+];
+/** Max string length heuristic — names/notes tend to be longer. */
+const MAX_SAFE_STRING_LENGTH = 50;
+// ── Scrubbing logic ──────────────────────────────────────────────────────
+/**
+ * Scrubs PII from a plan payload, keeping only the mathematical fields
+ * required for cloud compute.
+ */
+export function scrubPII(plan) {
+    const removedFields = [];
+    const payload = scrubObject(plan, ALLOWED_TOP_LEVEL, "", removedFields);
+    return { payload, removedFields };
+}
+function scrubObject(obj, allowedKeys, parentPath, removed) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fieldPath = parentPath ? `${parentPath}.${key}` : key;
+        if (!allowedKeys.has(key)) {
+            removed.push(fieldPath);
+            continue;
+        }
+        if (value === null || value === undefined) {
+            result[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            result[key] = scrubArray(key, value, fieldPath, removed);
+        }
+        else if (typeof value === "object") {
+            result[key] = scrubNestedObject(key, value, fieldPath, removed);
+        }
+        else {
+            // Primitives — keep numbers/booleans, validate strings
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function scrubArray(key, arr, parentPath, removed) {
+    if (key === "accounts") {
+        return arr.map((item, i) => typeof item === "object" && item !== null
+            ? scrubObject(item, ALLOWED_ACCOUNT_FIELDS, `${parentPath}[${i}]`, removed)
+            : item);
+    }
+    if (key === "incomeStreams") {
+        return arr.map((item, i) => typeof item === "object" && item !== null
+            ? scrubObject(item, ALLOWED_INCOME_FIELDS, `${parentPath}[${i}]`, removed)
+            : item);
+    }
+    // Generic array — pass through (for component arrays, etc.)
+    return arr;
+}
+function scrubNestedObject(key, obj, parentPath, removed) {
+    if (key === "spouse") {
+        return scrubObject(obj, ALLOWED_SPOUSE_FIELDS, parentPath, removed);
+    }
+    if (key === "socialSecurity") {
+        return scrubObject(obj, ALLOWED_SS_FIELDS, parentPath, removed);
+    }
+    // For nested objects like 'household', 'goals', 'overrides', 'strategy',
+    // 'assumptions', 'taxProfile' — recurse with ALLOWED_TOP_LEVEL since
+    // these may contain nested plan-like structures
+    return scrubObject(obj, ALLOWED_TOP_LEVEL, parentPath, removed);
+}
+// ── Validation ───────────────────────────────────────────────────────────
+/**
+ * Deep-scans a payload to ensure no PII has leaked through.
+ * Returns `true` if the payload is PII-free.
+ */
+export function validateNoPII(payload) {
+    return !containsPII(payload);
+}
+function containsPII(value) {
+    if (typeof value === "string") {
+        // Allow known enum values
+        if (KNOWN_ENUM_VALUES.has(value))
+            return false;
+        // Flag long strings that aren't enum values
+        if (value.length > MAX_SAFE_STRING_LENGTH)
+            return true;
+        // Check against PII patterns
+        return PII_PATTERNS.some((pattern) => pattern.test(value));
+    }
+    if (Array.isArray(value)) {
+        return value.some(containsPII);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.values(value).some(containsPII);
+    }
+    return false;
+}

package/dist/src/policy/policy-engine.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Policy Engine Adapter — FEAT-0056
+ *
+ * Evaluates role/tool/action permissions against the policy baseline
+ * before tool execution. Returns machine-readable policy decisions
+ * with explicit deny reasons.
+ *
+ * @feature FEAT-0056
+ */
+export type PolicyDecisionOutcome = "allow" | "deny";
+export interface PolicyDecision {
+    decisionId: string;
+    actorId: string;
+    toolName: string;
+    decision: PolicyDecisionOutcome;
+    reasonCodes: string[];
+    evaluatedAt: string;
+}
+export type UserRole = "anonymous" | "authenticated" | "advisor" | "admin";
+export interface PolicyContext {
+    actorId: string;
+    role: UserRole;
+    toolName: string;
+}
+export declare const REASON: {
+    readonly TOOL_NOT_IN_ALLOWLIST: "TOOL_NOT_IN_ALLOWLIST";
+    readonly ROLE_INSUFFICIENT: "ROLE_INSUFFICIENT";
+    readonly PRIVILEGED_TOOL_REQUIRES_ADVISOR: "PRIVILEGED_TOOL_REQUIRES_ADVISOR";
+    readonly TOOL_UNREGISTERED: "TOOL_UNREGISTERED";
+};
+/**
+ * Evaluates whether the given actor/role may invoke the specified tool.
+ * Returns a machine-readable PolicyDecision with explicit deny reasons.
+ */
+export declare function evaluatePolicy(ctx: PolicyContext): PolicyDecision;
+/**
+ * Convenience: evaluates policy and throws if denied.
+ * Returns the allow decision for provenance/audit purposes.
+ */
+export declare function requirePolicy(ctx: PolicyContext): PolicyDecision;
+/**
+ * Resets the decision counter (for testing only).
+ */
+export declare function _resetDecisionCounter(): void;

package/dist/src/policy/policy-engine.js

@@ -0,0 +1,119 @@
+/**
+ * Policy Engine Adapter — FEAT-0056
+ *
+ * Evaluates role/tool/action permissions against the policy baseline
+ * before tool execution. Returns machine-readable policy decisions
+ * with explicit deny reasons.
+ *
+ * @feature FEAT-0056
+ */
+// ── Reason codes ─────────────────────────────────────────────────────────
+export const REASON = {
+    TOOL_NOT_IN_ALLOWLIST: "TOOL_NOT_IN_ALLOWLIST",
+    ROLE_INSUFFICIENT: "ROLE_INSUFFICIENT",
+    PRIVILEGED_TOOL_REQUIRES_ADVISOR: "PRIVILEGED_TOOL_REQUIRES_ADVISOR",
+    TOOL_UNREGISTERED: "TOOL_UNREGISTERED",
+};
+// ── Role-based tool allowlists ───────────────────────────────────────────
+const ROLE_ALLOWLISTS = {
+    admin: "all",
+    advisor: "all",
+    authenticated: new Set([
+        "create_plan",
+        "run_forecast",
+        "run_scenario",
+        "verify_forecast",
+        "coach",
+        "medicare-guardian",
+        "medicare-analyze",
+        "retirement-planner",
+        "email-subscribe",
+        "optimize_roth_conversion",
+        // plan management
+        "list_plans",
+        "get_plan",
+        "get_active_plan",
+        "create_saved_plan",
+        "save_plan",
+        "activate_plan",
+        "delete_plan",
+        "rename_plan",
+        "get_plan_components",
+        // forecast management
+        "run_saved_forecast",
+        "get_baseline_forecast",
+        // scenario management
+        "save_scenario",
+        "list_scenarios",
+        "get_scenario",
+        "delete_scenario",
+        // comprehensive
+        "comprehensive_plan",
+    ]),
+    anonymous: new Set([
+        "create_plan",
+        "run_forecast",
+        "coach",
+        "medicare-guardian",
+        "medicare-analyze",
+        "retirement-planner",
+    ]),
+};
+// Tools that require at least advisor role
+const PRIVILEGED_TOOLS = new Set([
+// Currently none are privileged-only, but the gate is ready.
+// Future: tools that can execute transactions or modify advisor records.
+]);
+// ── Policy evaluation ────────────────────────────────────────────────────
+let decisionCounter = 0;
+function generateDecisionId() {
+    decisionCounter += 1;
+    return `pd-${Date.now()}-${decisionCounter}`;
+}
+/**
+ * Evaluates whether the given actor/role may invoke the specified tool.
+ * Returns a machine-readable PolicyDecision with explicit deny reasons.
+ */
+export function evaluatePolicy(ctx) {
+    const reasonCodes = [];
+    // Check privileged tool gate
+    if (PRIVILEGED_TOOLS.has(ctx.toolName)) {
+        if (ctx.role !== "advisor" && ctx.role !== "admin") {
+            reasonCodes.push(REASON.PRIVILEGED_TOOL_REQUIRES_ADVISOR);
+        }
+    }
+    // Check role allowlist
+    const allowlist = ROLE_ALLOWLISTS[ctx.role];
+    if (allowlist !== "all" && !allowlist.has(ctx.toolName)) {
+        reasonCodes.push(REASON.TOOL_NOT_IN_ALLOWLIST);
+    }
+    const decision = reasonCodes.length === 0 ? "allow" : "deny";
+    return {
+        decisionId: generateDecisionId(),
+        actorId: ctx.actorId,
+        toolName: ctx.toolName,
+        decision,
+        reasonCodes,
+        evaluatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Convenience: evaluates policy and throws if denied.
+ * Returns the allow decision for provenance/audit purposes.
+ */
+export function requirePolicy(ctx) {
+    const decision = evaluatePolicy(ctx);
+    if (decision.decision === "deny") {
+        const err = new Error(`Policy denied: tool '${ctx.toolName}' for role '${ctx.role}' — [${decision.reasonCodes.join(", ")}]`);
+        err.policyDecision =
+            decision;
+        throw err;
+    }
+    return decision;
+}
+/**
+ * Resets the decision counter (for testing only).
+ */
+export function _resetDecisionCounter() {
+    decisionCounter = 0;
+}

package/dist/src/rate-limit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * In-memory rate limiter — sliding window per key.
+ * Adapted from mcp-edge.
+ */
+export interface RateLimitDecision {
+    allowed: boolean;
+    remaining: number;
+    resetAtMs: number;
+    retryAfterSeconds: number;
+}
+export declare class InMemoryRateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly buckets;
+    constructor(windowMs: number, maxRequests: number);
+    check(key: string, nowMs?: number): RateLimitDecision;
+}