@scales-baby/nest-bridge 1.0.0

package/dist/crypto/primitives.js

@@ -0,0 +1,134 @@
+"use strict";
+// Nest encryption — client-side WebCrypto primitives.
+//
+// THE ENCRYPTION ENGINE. Everything here runs via WebCrypto (crypto.subtle).
+// These are the shared building blocks the per-method KEK derivers and the
+// unlock flow use:
+//
+//   - base64url encode/decode (matches the server's WrappedDek string fields)
+//   - random DEK generation (32 bytes / 256-bit)
+//   - AES-256-GCM encrypt/decrypt (used for BOTH wrapping the DEK and for
+//     encrypting CRM content fields)
+//   - HKDF-SHA256 to stretch a raw IKM into a clean 256-bit KEK
+//
+// These run identically in the browser (the Nest web app) and in Node 20+
+// (this bridge): crypto.subtle, btoa/atob, TextEncoder/TextDecoder are all
+// global in both. That is how the bridge derives the SAME KEK/DEK and produces
+// the SAME ciphertext as the web client.
+//
+// Hard rule: the server must NEVER receive the DEK, a KEK, or plaintext
+// content. These functions only ever hand wrapped/ciphertext blobs to the
+// network layer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bytesToB64u = bytesToB64u;
+exports.b64uToBytes = b64uToBytes;
+exports.utf8 = utf8;
+exports.fromUtf8 = fromUtf8;
+exports.generateDek = generateDek;
+exports.aesGcmEncrypt = aesGcmEncrypt;
+exports.aesGcmDecrypt = aesGcmDecrypt;
+exports.hkdfKek = hkdfKek;
+// ---------------------------------------------------------------------------
+// base64url (no padding) — the on-wire format for every encrypted/binding field
+// ---------------------------------------------------------------------------
+function bytesToB64u(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64uToBytes(s) {
+    const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + pad;
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+function fromUtf8(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+// ---------------------------------------------------------------------------
+// DEK generation — one random 256-bit key per user, generated client-side
+// ---------------------------------------------------------------------------
+// A fresh 32-byte (256-bit) Data Encryption Key. NEVER sent to the server in
+// this form — only ever wrapped under a KEK first (see envelope.ts).
+function generateDek() {
+    return crypto.getRandomValues(new Uint8Array(32));
+}
+// ---------------------------------------------------------------------------
+// AES-256-GCM — content encryption AND DEK wrapping
+// ---------------------------------------------------------------------------
+async function importAesKey(keyBytes, usage) {
+    if (keyBytes.length !== 32) {
+        throw new Error("aes_key_must_be_256_bit");
+    }
+    return crypto.subtle.importKey("raw", bufferSource(keyBytes), "AES-GCM", false, usage);
+}
+// Encrypt `plaintext` under a 256-bit key. Returns { iv, ct, tag } as base64url.
+// `aad` (additional authenticated data) is optional and bound into the tag.
+async function aesGcmEncrypt(keyBytes, plaintext, aad) {
+    const key = await importAesKey(keyBytes, ["encrypt"]);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const params = { name: "AES-GCM", iv: bufferSource(iv) };
+    if (aad)
+        params.additionalData = bufferSource(aad);
+    const buf = new Uint8Array(await crypto.subtle.encrypt(params, key, bufferSource(plaintext)));
+    // WebCrypto appends the 16-byte tag to the ciphertext.
+    return {
+        iv: bytesToB64u(iv),
+        ct: bytesToB64u(buf.slice(0, buf.length - 16)),
+        tag: bytesToB64u(buf.slice(buf.length - 16)),
+    };
+}
+// Decrypt an { iv, ct, tag } blob under a 256-bit key. Throws if the tag fails
+// (wrong key / tampered ciphertext) — which is exactly the integrity guarantee.
+async function aesGcmDecrypt(keyBytes, blob, aad) {
+    const key = await importAesKey(keyBytes, ["decrypt"]);
+    const ct = b64uToBytes(blob.ct);
+    const tag = b64uToBytes(blob.tag);
+    const joined = new Uint8Array(ct.length + tag.length);
+    joined.set(ct, 0);
+    joined.set(tag, ct.length);
+    const params = {
+        name: "AES-GCM",
+        iv: bufferSource(b64uToBytes(blob.iv)),
+    };
+    if (aad)
+        params.additionalData = bufferSource(aad);
+    const buf = await crypto.subtle.decrypt(params, key, bufferSource(joined));
+    return new Uint8Array(buf);
+}
+// ---------------------------------------------------------------------------
+// HKDF-SHA256 — stretch raw IKM into a 256-bit KEK
+// ---------------------------------------------------------------------------
+// Fixed application salt + info so the same IKM always derives the same KEK.
+// Domain-bound so input keying material captured for Nest can't be reused to
+// derive a key in another app.
+const HKDF_SALT = utf8("nest.scales.baby/kek/v1");
+// Derive a 256-bit KEK from raw input keying material. `info` further separates
+// keys derived from the same IKM for different purposes if ever needed.
+async function hkdfKek(ikm, info = "nest-dek-wrap-v1") {
+    const baseKey = await crypto.subtle.importKey("raw", bufferSource(ikm), "HKDF", false, ["deriveBits"]);
+    const bits = await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: bufferSource(HKDF_SALT),
+        info: bufferSource(utf8(info)),
+    }, baseKey, 256);
+    return new Uint8Array(bits);
+}
+// WebCrypto's BufferSource typing (TS 5.7+) distinguishes
+// Uint8Array<ArrayBuffer> from Uint8Array<ArrayBufferLike> (the latter could be
+// SharedArrayBuffer-backed). Copy into a fresh, exactly-sized ArrayBuffer and
+// return an ArrayBuffer (not a view), which satisfies BufferSource cleanly and
+// is also a runtime no-op-safe copy.
+function bufferSource(bytes) {
+    const ab = new ArrayBuffer(bytes.length);
+    new Uint8Array(ab).set(bytes);
+    return ab;
+}

package/dist/crypto.js

@@ -0,0 +1,40 @@
+"use strict";
+// Bridge crypto — REUSES the EXACT same client crypto modules the Nest web app
+// uses, so reads/writes round-trip byte-for-byte with the browser.
+//
+// We import the shared crypto from ./crypto/*. Those modules are pure WebCrypto
+// (crypto.subtle) + hash-wasm Argon2id + btoa/atob/TextEncoder/TextDecoder —
+// ALL global in Node 20+. Nothing here is browser-only (no IndexedDB, no DOM),
+// so it runs unchanged in this Node process. This is how we GUARANTEE the
+// bridge derives the same KEK/DEK and produces the same `enc` ciphertext as the
+// web client.
+//
+// SECURITY INVARIANT: the DEK and password live ONLY in this process's memory.
+// The Nest server only ever receives the wrapped-DEK fetch (it sends US the
+// wrap), ciphertext on writes, and never the password/DEK/plaintext.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hydrateRecord = exports.buildWritePayload = exports.CONTENT_SCHEMA = void 0;
+exports.unlockDekWithPassword = unlockDekWithPassword;
+exports.encryptedFieldsFor = encryptedFieldsFor;
+const password_1 = require("./crypto/kek/password");
+const envelope_1 = require("./crypto/envelope");
+const crmData_1 = require("./crypto/crmData");
+Object.defineProperty(exports, "buildWritePayload", { enumerable: true, get: function () { return crmData_1.buildWritePayload; } });
+Object.defineProperty(exports, "hydrateRecord", { enumerable: true, get: function () { return crmData_1.hydrateRecord; } });
+const contentSchema_1 = require("./crypto/contentSchema");
+Object.defineProperty(exports, "CONTENT_SCHEMA", { enumerable: true, get: function () { return contentSchema_1.CONTENT_SCHEMA; } });
+// Derive the password KEK (Argon2id, matching the browser exactly) from the
+// stored salt/params, then unwrap the DEK locally. Returns the raw DEK bytes —
+// they never leave this process.
+async function unlockDekWithPassword(password, wrap) {
+    if (!wrap.kdfSalt)
+        throw new Error("password_salt_missing");
+    const kek = await (0, password_1.derivePasswordKek)(password, wrap.kdfSalt, wrap.kdf);
+    const dek = await (0, envelope_1.unwrapDek)(kek, wrap);
+    return { dek, dekVersion: wrap.dekVersion ?? 1 };
+}
+// The encrypted-vs-clear field split, for callers that want to know which keys
+// a model encrypts (e.g. to validate a write payload).
+function encryptedFieldsFor(model) {
+    return contentSchema_1.CONTENT_SCHEMA[model].encrypted;
+}

package/dist/data.js

@@ -0,0 +1,113 @@
+"use strict";
+// Bridge — the CRM data layer: encrypt-on-write / decrypt-on-read.
+//
+// READ:  fetch ciphertext from the Nest REST API → hydrateRecord() with the DEK
+//        locally → return plaintext to the MCP caller (Claude).
+// WRITE: take the caller's plaintext → buildWritePayload() encrypts the
+//        sensitive fields into an `enc` blob + blanks plaintext locally → POST
+//        the ciphertext to the Nest API (the server stamps ownerId, stores the
+//        blob, never sees plaintext or the DEK).
+//
+// When the account is UNENCRYPTED (no DEK), everything is a pass-through — the
+// server stores/returns plaintext exactly as the web app does.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataLayer = void 0;
+const crypto_1 = require("./crypto");
+// Map a CrmModel to its REST collection path.
+const PATHS = {
+    person: "/api/people",
+    company: "/api/companies",
+    task: "/api/tasks",
+    event: "/api/events",
+    merchant: "/api/merchants",
+    route: "/api/routes",
+};
+class DataLayer {
+    client;
+    vault;
+    constructor(client, vault) {
+        this.client = client;
+        this.vault = vault;
+    }
+    path(model) {
+        return PATHS[model];
+    }
+    // --- READS ---------------------------------------------------------------
+    async list(model, query = {}) {
+        const qs = Object.entries(query)
+            .filter(([, v]) => v !== undefined && v !== "")
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join("&");
+        const path = qs ? `${this.path(model)}?${qs}` : this.path(model);
+        const rows = (await this.client.get(path)) ?? [];
+        return Promise.all(rows.map((r) => this.decrypt(model, r)));
+    }
+    async get(model, id) {
+        const row = await this.client.get(`${this.path(model)}/${id}`);
+        if (!row)
+            return null;
+        return this.decrypt(model, row);
+    }
+    async decrypt(model, row) {
+        // hydrateRecord is a no-op for plaintext docs (no `enc`) and for unencrypted
+        // accounts (dek=null leaves blanks). With the DEK it merges decrypted
+        // content back over the cleartext metadata.
+        try {
+            return (await (0, crypto_1.hydrateRecord)(model, this.vault.dek, row));
+        }
+        catch {
+            // A single corrupt blob shouldn't blank the whole call — return as-is.
+            return row;
+        }
+    }
+    // --- WRITES --------------------------------------------------------------
+    // Create: `fields` is the caller's plaintext. We encrypt locally (if the
+    // account is encrypted) and POST ciphertext. Returns the created record,
+    // decrypted back for the caller.
+    async create(model, fields) {
+        const payload = await (0, crypto_1.buildWritePayload)(model, {
+            encrypted: this.vault.encrypted,
+            dek: this.vault.dek,
+            dekVersion: this.vault.dekVersion,
+        }, fields, fields);
+        const created = await this.client.post(this.path(model), payload);
+        if (!created)
+            return null;
+        return this.decrypt(model, created);
+    }
+    // Update: PATCH. For an encrypted account, `enc` is ONE per-doc blob, so we
+    // must re-encrypt the COMPLETE sensitive set. We fetch + decrypt the current
+    // record, merge the caller's changes on top, then build the write from the
+    // merged full record (sensitive) + the caller's changes (cleartext only).
+    async update(model, id, changes) {
+        let payload;
+        if (this.vault.encrypted && this.vault.dek) {
+            const current = await this.get(model, id); // decrypted
+            const merged = { ...(current ?? {}), ...changes };
+            payload = await (0, crypto_1.buildWritePayload)(model, {
+                encrypted: true,
+                dek: this.vault.dek,
+                dekVersion: this.vault.dekVersion,
+            }, merged, changes);
+        }
+        else {
+            // Unencrypted: pass the caller's changes through.
+            payload = await (0, crypto_1.buildWritePayload)(model, { encrypted: false, dek: null }, changes, changes);
+        }
+        const updated = await this.client.patch(`${this.path(model)}/${id}`, payload);
+        if (!updated)
+            return null;
+        return this.decrypt(model, updated);
+    }
+    // Convenience: mark a task done (metadata-only write, never touches content).
+    async completeTask(id) {
+        const updated = await this.client.patch(`${this.path("task")}/${id}`, { status: "done" });
+        if (!updated)
+            return null;
+        return this.decrypt("task", updated);
+    }
+    async digest() {
+        return this.client.get("/api/digest");
+    }
+}
+exports.DataLayer = DataLayer;

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"use strict";
+// Nest local MCP bridge — entry point.
+//
+// Runs on the USER's machine. Holds the user's DEK in memory after deriving it
+// from their PASSWORD; the Nest SERVER never receives the DEK, the password, or
+// plaintext. Reads decrypt locally, writes encrypt locally.
+//
+// Config (env or .env in cwd):
+//   NEST_API_URL   default https://nest.scales.baby
+//   NEST_API_KEY   the user's scoped key (nest_<prefix>_<secret>)  [required]
+//   NEST_PASSWORD  OPTIONAL — if unset, prompt securely at startup (preferred)
+//
+// All logging goes to stderr so it never corrupts the stdio MCP protocol.
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const nestClient_1 = require("./nestClient");
+const crypto_1 = require("./crypto");
+const data_1 = require("./data");
+const mcp_1 = require("./mcp");
+const prompt_1 = require("./prompt");
+const log = (...a) => console.error("[nest-bridge]", ...a);
+const WRITE_SCOPES = new Set(["crm:write", "tasks:write"]);
+// True only when launched from a real interactive terminal where a hidden
+// password prompt is safe. Claude Desktop / OpenAI launch us non-interactively
+// (stdio wired to the MCP client), so this is false there and we never touch
+// the protocol pipe trying to read a password.
+function hasInteractiveTty() {
+    if (process.env.NEST_NON_INTERACTIVE === "1")
+        return false;
+    try {
+        // openSync throws if there is no controlling terminal.
+        const fd = (0, node_fs_1.openSync)("/dev/tty", "r");
+        (0, node_fs_1.closeSync)(fd);
+        return true;
+    }
+    catch {
+        return process.stdin.isTTY === true && process.stdout.isTTY === true;
+    }
+}
+async function main() {
+    const apiUrl = process.env.NEST_API_URL || "https://nest.scales.baby";
+    const apiKey = process.env.NEST_API_KEY || "";
+    if (!apiKey) {
+        log("Missing NEST_API_KEY. Mint a scoped key in Nest → Settings → Connect your AI, then set NEST_API_KEY.");
+        process.exit(1);
+    }
+    const client = new nestClient_1.NestClient({ apiUrl, apiKey });
+    // 1) Fetch the password-wrapped DEK blob + the account's encryption state.
+    log(`Connecting to ${apiUrl} …`);
+    let wrapInfo;
+    try {
+        wrapInfo = await client.getBridgeWrap();
+    }
+    catch (e) {
+        log("Failed to reach Nest or authenticate the API key:", e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+    const encrypted = wrapInfo.encState === "encrypted";
+    let vault = { encrypted, dek: null, dekVersion: 1 };
+    if (!encrypted) {
+        log("Account is NOT end-to-end encrypted — running in pass-through mode (no key needed).");
+    }
+    else if (!wrapInfo.hasPasswordWrap || !wrapInfo.wrap) {
+        log("Account is encrypted but has NO password unlock method. The bridge unlocks by password; add a password method in Nest → Settings → Encryption, then retry. Continuing LOCKED (content will be blank).");
+    }
+    else {
+        // 2) Get the password. Priority: env/connector config (NEST_PASSWORD) for
+        // non-interactive launches (Claude Desktop / OpenAI inject user_config as
+        // env), else a hidden TTY prompt for manual terminal runs. When launched
+        // WITHOUT a real interactive terminal AND without NEST_PASSWORD (e.g. a
+        // Claude Desktop connector with the field left blank), DO NOT try to read
+        // the MCP stdio pipe — continue locked with a clear message instead.
+        let password = process.env.NEST_PASSWORD || "";
+        if (!password) {
+            const interactive = hasInteractiveTty();
+            if (interactive) {
+                password = await (0, prompt_1.promptHidden)("Nest encryption password: ");
+            }
+            else {
+                log("No NEST_PASSWORD set and no interactive terminal — set the password in your connector config (Claude Desktop / OpenAI) or run the bridge in a terminal to be prompted. Continuing LOCKED (content will be blank).");
+            }
+        }
+        if (!password) {
+            log("No password provided — continuing LOCKED (content will be blank).");
+        }
+        else {
+            // 3) Derive the password KEK (Argon2id, matches the browser) → unwrap DEK.
+            log("Deriving key (Argon2id) and unwrapping the DEK locally …");
+            try {
+                const { dek, dekVersion } = await (0, crypto_1.unlockDekWithPassword)(password, wrapInfo.wrap);
+                vault = { encrypted: true, dek, dekVersion };
+                log("Unlocked. The DEK is held in memory only; the server never sees it.");
+            }
+            catch (e) {
+                log("Unlock FAILED (wrong password or wrap mismatch):", e instanceof Error ? e.message : String(e), "— continuing LOCKED.");
+            }
+        }
+        // Best-effort scrub of the password reference.
+        password = "";
+    }
+    // Determine write capability from the key's scopes (the server still enforces
+    // authoritatively per-route). The bridge-wrap endpoint reports the key's
+    // scopes; a read-only key gets a clean "read-only" message instead of a 403.
+    const scopes = wrapInfo.scopes ?? [];
+    let canWrite = scopes.some((s) => WRITE_SCOPES.has(s));
+    if (process.env.NEST_READ_ONLY === "1")
+        canWrite = false;
+    log(`Key scopes: ${scopes.join(", ") || "(unknown)"} → ${canWrite ? "read+write" : "read-only"}.`);
+    const data = new data_1.DataLayer(client, vault);
+    const server = await (0, mcp_1.buildServer)({
+        data,
+        canWrite,
+        encrypted,
+        unlocked: vault.dek !== null,
+    });
+    await (0, mcp_1.runStdio)(server);
+    log("MCP server ready (stdio). Connect Claude to this process.");
+}
+main().catch((e) => {
+    console.error("[nest-bridge] fatal:", e);
+    process.exit(1);
+});