@nestpilot/mcp-app 1.0.0

package/dist/src/local/cloud-compute-client.js

@@ -0,0 +1,135 @@
+/**
+ * Cloud Compute Client — sends PII-free mathematical payloads to the
+ * NestPilot cloud API for compute-intensive operations (forecast, scenario,
+ * Roth optimization, coaching).
+ *
+ * All requests include:
+ *  - `Authorization: Bearer {apiKey}` for metering
+ *  - `X-Client-Mode: local` to distinguish local-first traffic
+ *  - 30 second timeout
+ *
+ * On network failure, the client returns cached results when available.
+ *
+ * @feature FEAT-0087
+ */
+// ── Configuration ────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 30_000;
+// ── CloudComputeClient ───────────────────────────────────────────────────
+export class CloudComputeClient {
+    cloudApiUrl;
+    apiKey;
+    constructor(cloudApiUrl, apiKey) {
+        this.cloudApiUrl = cloudApiUrl;
+        this.apiKey = apiKey;
+        // Strip trailing slash
+        if (this.cloudApiUrl.endsWith("/")) {
+            this.cloudApiUrl = this.cloudApiUrl.slice(0, -1);
+        }
+    }
+    /**
+     * Run a retirement forecast against the cloud engine.
+     */
+    async forecast(payload) {
+        return this.post("/api/plan/forecast", payload);
+    }
+    /**
+     * Run a what-if scenario comparison against the cloud engine.
+     */
+    async scenario(payload) {
+        return this.post("/api/plan/scenario/run", payload);
+    }
+    /**
+     * Run Roth conversion optimization against the cloud engine.
+     */
+    async rothOptimize(payload) {
+        return this.post("/api/plan/roth/optimize", payload);
+    }
+    /**
+     * Get AI coaching guidance from the cloud engine.
+     */
+    async coach(payload) {
+        return this.post("/api/spring_ai/coach", payload);
+    }
+    /**
+     * Run forecast verification against the cloud engine.
+     */
+    async verify(payload) {
+        return this.post("/api/plan/forecast/verify", payload);
+    }
+    /**
+     * Quick-calc for initial plan creation.
+     */
+    async quickCalc(payload) {
+        return this.post("/api/plan/calc", payload);
+    }
+    /**
+     * Health check — verifies the cloud API is reachable.
+     */
+    async healthCheck() {
+        try {
+            const response = await fetch(`${this.cloudApiUrl}/actuator/health`, {
+                method: "GET",
+                headers: this.buildHeaders(),
+                signal: AbortSignal.timeout(5_000),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Internal ──────────────────────────────────────────────────────────
+    async post(endpoint, payload) {
+        const url = `${this.cloudApiUrl}${endpoint}`;
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: this.buildHeaders(),
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                // Rate limiting
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get("Retry-After");
+                    return {
+                        error: true,
+                        message: `Cloud API rate limit exceeded. ${retryAfter
+                            ? `Retry after ${retryAfter} seconds.`
+                            : "Please wait and try again."} You may be on the free tier (10 forecasts/month). Upgrade at https://nestpilot.com/pricing.`,
+                    };
+                }
+                return {
+                    error: true,
+                    message: `Cloud API error (${response.status}): ${text}`,
+                };
+            }
+            const data = (await response.json());
+            return { data };
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            // Distinguish timeout from network errors
+            if (errorMessage.includes("abort") || errorMessage.includes("timeout")) {
+                return {
+                    error: true,
+                    message: "Cloud API request timed out after 30 seconds. The compute engine may be under heavy load. Try again shortly.",
+                };
+            }
+            return {
+                error: true,
+                message: `Cannot reach NestPilot cloud API at ${this.cloudApiUrl}. Check your internet connection. Error: ${errorMessage}`,
+            };
+        }
+    }
+    buildHeaders() {
+        return {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            "X-Client-Mode": "local",
+            "X-Client-Version": "1.0.0",
+        };
+    }
+}

package/dist/src/local/encryption.d.ts

@@ -0,0 +1,24 @@
+import type { KeychainProvider } from "./keychain.js";
+export declare class EncryptionService {
+    private keyProvider;
+    private cachedKey;
+    constructor(keyProvider: KeychainProvider);
+    /**
+     * Encrypts a UTF-8 string into an NPE envelope buffer.
+     */
+    encrypt(data: string): Promise<Buffer>;
+    /**
+     * Decrypts an NPE envelope buffer back into a UTF-8 string.
+     */
+    decrypt(envelope: Buffer): Promise<string>;
+    /**
+     * Generates a fresh 256-bit encryption key and stores it in the keychain.
+     * Returns the hex-encoded key.
+     */
+    generateAndStoreKey(): Promise<string>;
+    /**
+     * Checks whether an encryption key exists in the keychain.
+     */
+    hasKey(): Promise<boolean>;
+    private getKey;
+}

package/dist/src/local/encryption.js

@@ -0,0 +1,105 @@
+/**
+ * AES-256-GCM encryption for NestPilot data at rest.
+ *
+ * All plan data stored under ~/.nestpilot/ is encrypted using a key
+ * fetched from the OS keychain. The envelope format is:
+ *
+ *   [3-byte magic "NPE"] [1-byte version] [12-byte IV] [ciphertext] [16-byte auth tag]
+ *
+ * @feature FEAT-0087
+ */
+import { createCipheriv, createDecipheriv, randomBytes, } from "node:crypto";
+// ── Constants ────────────────────────────────────────────────────────────
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12; // 96 bits — GCM recommended
+const AUTH_TAG_LENGTH = 16;
+const MAGIC = Buffer.from("NPE"); // NestPilot Encrypted
+const ENVELOPE_VERSION = 1;
+const HEADER_LENGTH = MAGIC.length + 1 + IV_LENGTH; // 3 + 1 + 12 = 16
+const KEYCHAIN_SERVICE = "nestpilot";
+const KEYCHAIN_ENCRYPTION_ACCOUNT = "encryption-key";
+// ── EncryptionService ────────────────────────────────────────────────────
+export class EncryptionService {
+    keyProvider;
+    cachedKey = null;
+    constructor(keyProvider) {
+        this.keyProvider = keyProvider;
+    }
+    /**
+     * Encrypts a UTF-8 string into an NPE envelope buffer.
+     */
+    async encrypt(data) {
+        const key = await this.getKey();
+        const iv = randomBytes(IV_LENGTH);
+        const cipher = createCipheriv(ALGORITHM, key, iv, {
+            authTagLength: AUTH_TAG_LENGTH,
+        });
+        const encrypted = Buffer.concat([
+            cipher.update(data, "utf-8"),
+            cipher.final(),
+        ]);
+        const authTag = cipher.getAuthTag();
+        // Envelope: MAGIC + VERSION + IV + CIPHERTEXT + AUTH_TAG
+        return Buffer.concat([
+            MAGIC,
+            Buffer.from([ENVELOPE_VERSION]),
+            iv,
+            encrypted,
+            authTag,
+        ]);
+    }
+    /**
+     * Decrypts an NPE envelope buffer back into a UTF-8 string.
+     */
+    async decrypt(envelope) {
+        // Validate magic
+        if (envelope.length < HEADER_LENGTH + AUTH_TAG_LENGTH ||
+            !envelope.subarray(0, MAGIC.length).equals(MAGIC)) {
+            throw new Error("Invalid encrypted envelope: bad magic header");
+        }
+        const version = envelope[MAGIC.length];
+        if (version !== ENVELOPE_VERSION) {
+            throw new Error(`Unsupported encryption version: ${version}`);
+        }
+        const iv = envelope.subarray(MAGIC.length + 1, HEADER_LENGTH);
+        const authTag = envelope.subarray(envelope.length - AUTH_TAG_LENGTH);
+        const ciphertext = envelope.subarray(HEADER_LENGTH, envelope.length - AUTH_TAG_LENGTH);
+        const key = await this.getKey();
+        const decipher = createDecipheriv(ALGORITHM, key, iv, {
+            authTagLength: AUTH_TAG_LENGTH,
+        });
+        decipher.setAuthTag(authTag);
+        return Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final(),
+        ]).toString("utf-8");
+    }
+    /**
+     * Generates a fresh 256-bit encryption key and stores it in the keychain.
+     * Returns the hex-encoded key.
+     */
+    async generateAndStoreKey() {
+        const key = randomBytes(32).toString("hex");
+        await this.keyProvider.set(KEYCHAIN_SERVICE, KEYCHAIN_ENCRYPTION_ACCOUNT, key);
+        this.cachedKey = Buffer.from(key, "hex");
+        return key;
+    }
+    /**
+     * Checks whether an encryption key exists in the keychain.
+     */
+    async hasKey() {
+        const raw = await this.keyProvider.get(KEYCHAIN_SERVICE, KEYCHAIN_ENCRYPTION_ACCOUNT);
+        return raw !== null;
+    }
+    // ── Internal ──────────────────────────────────────────────────────────
+    async getKey() {
+        if (this.cachedKey)
+            return this.cachedKey;
+        const raw = await this.keyProvider.get(KEYCHAIN_SERVICE, KEYCHAIN_ENCRYPTION_ACCOUNT);
+        if (!raw) {
+            throw new Error("Encryption key not found in keychain. Run `nestpilot init` to set up encryption.");
+        }
+        this.cachedKey = Buffer.from(raw, "hex");
+        return this.cachedKey;
+    }
+}

package/dist/src/local/keychain.d.ts

@@ -0,0 +1,41 @@
+export interface KeychainProvider {
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<void>;
+}
+declare class MacOSKeychain implements KeychainProvider {
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<void>;
+}
+declare class WindowsKeychain implements KeychainProvider {
+    private target;
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<void>;
+}
+declare class LinuxKeychain implements KeychainProvider {
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<void>;
+}
+/**
+ * Fallback keychain that stores credentials in a JSON file.
+ * Used when no OS keychain is available. The file itself should be
+ * in a protected directory with 0600 permissions.
+ */
+declare class FileKeychain implements KeychainProvider {
+    private filePath;
+    constructor(dataDir?: string);
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<void>;
+    private load;
+    private save;
+}
+/**
+ * Creates the appropriate KeychainProvider for the current platform.
+ * Falls back to file-based storage if no OS keychain is detected.
+ */
+export declare function createKeychainProvider(dataDir?: string): KeychainProvider;
+export { FileKeychain, LinuxKeychain, MacOSKeychain, WindowsKeychain };

package/dist/src/local/keychain.js

@@ -0,0 +1,236 @@
+/**
+ * OS-native keychain integration for NestPilot secrets.
+ *
+ * Provides a platform-agnostic interface for storing API keys and encryption
+ * keys in the operating system's secure credential store.
+ *
+ * Platform mapping:
+ *  - macOS  : Keychain (via `security` CLI)
+ *  - Windows: Windows Credential Manager (via `cmdkey` / PowerShell)
+ *  - Linux  : libsecret / Secret Service API (GNOME Keyring / KWallet)
+ *  - Fallback: Encrypted file at ~/.nestpilot/credentials.enc
+ *
+ * @feature FEAT-0087
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+// ── macOS Keychain ───────────────────────────────────────────────────────
+class MacOSKeychain {
+    async get(service, account) {
+        try {
+            const { stdout } = await execFileAsync("security", [
+                "find-generic-password",
+                "-s",
+                service,
+                "-a",
+                account,
+                "-w",
+            ]);
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(service, account, value) {
+        // Delete first to allow update
+        try {
+            await execFileAsync("security", [
+                "delete-generic-password",
+                "-s",
+                service,
+                "-a",
+                account,
+            ]);
+        }
+        catch {
+            // Ignore if not found
+        }
+        await execFileAsync("security", [
+            "add-generic-password",
+            "-s",
+            service,
+            "-a",
+            account,
+            "-w",
+            value,
+        ]);
+    }
+    async delete(service, account) {
+        try {
+            await execFileAsync("security", [
+                "delete-generic-password",
+                "-s",
+                service,
+                "-a",
+                account,
+            ]);
+        }
+        catch {
+            // Ignore if not found
+        }
+    }
+}
+// ── Windows Credential Manager ───────────────────────────────────────────
+class WindowsKeychain {
+    target(service, account) {
+        return `${service}:${account}`;
+    }
+    async get(service, account) {
+        try {
+            const target = this.target(service, account);
+            const { stdout } = await execFileAsync("powershell.exe", [
+                "-NoProfile",
+                "-Command",
+                `$cred = Get-StoredCredential -Target '${target}' -ErrorAction SilentlyContinue; if ($cred) { $cred.GetNetworkCredential().Password } else { $null }`,
+            ]);
+            const result = stdout.trim();
+            return result && result !== "" ? result : null;
+        }
+        catch {
+            // Fallback: try cmdkey
+            try {
+                const target = this.target(service, account);
+                const { stdout } = await execFileAsync("powershell.exe", [
+                    "-NoProfile",
+                    "-Command",
+                    `[System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR((New-Object System.Management.Automation.PSCredential('_', (cmdkey /generic:${target} /list 2>$null | Out-Null; [System.Security.SecureString]::new()))).Password))`,
+                ]);
+                return stdout.trim() || null;
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    async set(service, account, value) {
+        const target = this.target(service, account);
+        await execFileAsync("cmdkey", [
+            `/generic:${target}`,
+            `/user:${account}`,
+            `/pass:${value}`,
+        ]);
+    }
+    async delete(service, account) {
+        try {
+            const target = this.target(service, account);
+            await execFileAsync("cmdkey", [`/delete:${target}`]);
+        }
+        catch {
+            // Ignore if not found
+        }
+    }
+}
+// ── Linux Secret Service ─────────────────────────────────────────────────
+class LinuxKeychain {
+    async get(service, account) {
+        try {
+            const { stdout } = await execFileAsync("secret-tool", [
+                "lookup",
+                "service",
+                service,
+                "account",
+                account,
+            ]);
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(service, account, value) {
+        const child = execFileAsync("secret-tool", [
+            "store",
+            "--label",
+            `${service}:${account}`,
+            "service",
+            service,
+            "account",
+            account,
+        ]);
+        // secret-tool reads the secret from stdin
+        child.child.stdin?.write(value);
+        child.child.stdin?.end();
+        await child;
+    }
+    async delete(service, account) {
+        try {
+            await execFileAsync("secret-tool", [
+                "clear",
+                "service",
+                service,
+                "account",
+                account,
+            ]);
+        }
+        catch {
+            // Ignore if not found
+        }
+    }
+}
+// ── File-based fallback ──────────────────────────────────────────────────
+/**
+ * Fallback keychain that stores credentials in a JSON file.
+ * Used when no OS keychain is available. The file itself should be
+ * in a protected directory with 0600 permissions.
+ */
+class FileKeychain {
+    filePath;
+    constructor(dataDir) {
+        this.filePath = path.join(dataDir ?? path.join(os.homedir(), ".nestpilot"), "credentials.json");
+    }
+    async get(service, account) {
+        const data = await this.load();
+        return data[`${service}:${account}`] ?? null;
+    }
+    async set(service, account, value) {
+        const data = await this.load();
+        data[`${service}:${account}`] = value;
+        await this.save(data);
+    }
+    async delete(service, account) {
+        const data = await this.load();
+        delete data[`${service}:${account}`];
+        await this.save(data);
+    }
+    async load() {
+        try {
+            const raw = await fs.readFile(this.filePath, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    async save(data) {
+        const dir = path.dirname(this.filePath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(this.filePath, JSON.stringify(data, null, 2), {
+            mode: 0o600, // Owner read/write only
+        });
+    }
+}
+// ── Factory ──────────────────────────────────────────────────────────────
+/**
+ * Creates the appropriate KeychainProvider for the current platform.
+ * Falls back to file-based storage if no OS keychain is detected.
+ */
+export function createKeychainProvider(dataDir) {
+    const platform = os.platform();
+    switch (platform) {
+        case "darwin":
+            return new MacOSKeychain();
+        case "win32":
+            return new WindowsKeychain();
+        case "linux":
+            return new LinuxKeychain();
+        default:
+            console.warn(`[keychain] No native keychain support for ${platform}, using file-based fallback`);
+            return new FileKeychain(dataDir);
+    }
+}
+export { FileKeychain, LinuxKeychain, MacOSKeychain, WindowsKeychain };

package/dist/src/local/local-config.d.ts

@@ -0,0 +1,34 @@
+export type NestpilotMode = "cloud" | "local";
+export interface LocalConfig {
+    /** Runtime mode — "cloud" proxies to Spring Boot, "local" uses local data layer. */
+    mode: NestpilotMode;
+    /** Root directory for local data (default: ~/.nestpilot). */
+    dataDir: string;
+    /** Cloud API URL for PII-free compute calls. */
+    cloudApiUrl: string;
+    /** API key retrieved from keychain (populated lazily). */
+    apiKey?: string;
+    /** Whether data-at-rest encryption is active (always true in local mode). */
+    encryptionEnabled: boolean;
+}
+export declare const DATA_SUBDIRS: readonly ["plans", "forecasts", "scenarios", "logs"];
+export declare function plansDir(dataDir: string): string;
+export declare function forecastsDir(dataDir: string): string;
+export declare function scenariosDir(dataDir: string): string;
+export declare function logsDir(dataDir: string): string;
+export declare function configFilePath(dataDir: string): string;
+/**
+ * Loads the local configuration from environment variables.
+ *
+ * Environment variables:
+ *  - `NESTPILOT_MODE`          — "cloud" (default) or "local"
+ *  - `NESTPILOT_DATA_DIR`      — data root (default: ~/.nestpilot)
+ *  - `NESTPILOT_CLOUD_API_URL` — cloud compute URL
+ *  - `NESTPILOT_API_KEY`       — API key override (normally loaded from keychain)
+ */
+export declare function loadLocalConfig(env?: NodeJS.ProcessEnv): LocalConfig;
+/**
+ * Returns `true` when the server is running in local-first mode.
+ * Convenience function used by the server bootstrap.
+ */
+export declare function isLocalMode(env?: NodeJS.ProcessEnv): boolean;

package/dist/src/local/local-config.js

@@ -0,0 +1,61 @@
+/**
+ * Local-first mode detection and configuration.
+ *
+ * Reads NESTPILOT_MODE ("cloud" | "local") from the environment and
+ * builds the LocalConfig object that drives all local-first behavior.
+ *
+ * @feature FEAT-0087
+ */
+import os from "node:os";
+import path from "node:path";
+// ── Well-known paths inside dataDir ──────────────────────────────────────
+export const DATA_SUBDIRS = [
+    "plans",
+    "forecasts",
+    "scenarios",
+    "logs",
+];
+export function plansDir(dataDir) {
+    return path.join(dataDir, "plans");
+}
+export function forecastsDir(dataDir) {
+    return path.join(dataDir, "forecasts");
+}
+export function scenariosDir(dataDir) {
+    return path.join(dataDir, "scenarios");
+}
+export function logsDir(dataDir) {
+    return path.join(dataDir, "logs");
+}
+export function configFilePath(dataDir) {
+    return path.join(dataDir, "config.json");
+}
+// ── Configuration loader ─────────────────────────────────────────────────
+const DEFAULT_CLOUD_API_URL = "https://api.nestpilot.com";
+/**
+ * Loads the local configuration from environment variables.
+ *
+ * Environment variables:
+ *  - `NESTPILOT_MODE`          — "cloud" (default) or "local"
+ *  - `NESTPILOT_DATA_DIR`      — data root (default: ~/.nestpilot)
+ *  - `NESTPILOT_CLOUD_API_URL` — cloud compute URL
+ *  - `NESTPILOT_API_KEY`       — API key override (normally loaded from keychain)
+ */
+export function loadLocalConfig(env = process.env) {
+    const mode = (env.NESTPILOT_MODE ?? "cloud");
+    const dataDir = env.NESTPILOT_DATA_DIR ?? path.join(os.homedir(), ".nestpilot");
+    return {
+        mode,
+        dataDir,
+        cloudApiUrl: env.NESTPILOT_CLOUD_API_URL ?? DEFAULT_CLOUD_API_URL,
+        apiKey: env.NESTPILOT_API_KEY,
+        encryptionEnabled: mode === "local",
+    };
+}
+/**
+ * Returns `true` when the server is running in local-first mode.
+ * Convenience function used by the server bootstrap.
+ */
+export function isLocalMode(env = process.env) {
+    return (env.NESTPILOT_MODE ?? "cloud") === "local";
+}

package/dist/src/local/local-data-layer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Local Data Layer — barrel export for all local-first modules.
+ *
+ * Provides a single import point for the local runtime:
+ *
+ *   import { LocalPlanStore, CloudComputeClient, ... } from "./local/local-data-layer.js";
+ *
+ * @feature FEAT-0087
+ */
+export { loadLocalConfig, isLocalMode } from "./local-config.js";
+export type { NestpilotMode, LocalConfig } from "./local-config.js";
+export { EncryptionService } from "./encryption.js";
+export { createKeychainProvider, FileKeychain, } from "./keychain.js";
+export type { KeychainProvider } from "./keychain.js";
+export { LocalPlanStore } from "./local-plan-store.js";
+export type { LocalPlan, PlanSummary } from "./local-plan-store.js";
+export { scrubPII, validateNoPII } from "./pii-scrubber.js";
+export type { ScrubResult } from "./pii-scrubber.js";
+export { CloudComputeClient } from "./cloud-compute-client.js";
+export type { CloudComputeResult } from "./cloud-compute-client.js";

package/dist/src/local/local-data-layer.js

@@ -0,0 +1,15 @@
+/**
+ * Local Data Layer — barrel export for all local-first modules.
+ *
+ * Provides a single import point for the local runtime:
+ *
+ *   import { LocalPlanStore, CloudComputeClient, ... } from "./local/local-data-layer.js";
+ *
+ * @feature FEAT-0087
+ */
+export { loadLocalConfig, isLocalMode } from "./local-config.js";
+export { EncryptionService } from "./encryption.js";
+export { createKeychainProvider, FileKeychain, } from "./keychain.js";
+export { LocalPlanStore } from "./local-plan-store.js";
+export { scrubPII, validateNoPII } from "./pii-scrubber.js";
+export { CloudComputeClient } from "./cloud-compute-client.js";