fullstackgtm 0.26.0 → 0.28.0

package/dist/keychain.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Optional OS-keychain backing for the credential store. Off by default;
+ * enabled with FSGTM_KEYCHAIN=1. When on, the credential blob is stored in the
+ * OS secret store instead of a 0600 file, so a cloned home, a restored backup,
+ * or another tool reading `~/.fullstackgtm/credentials.json` finds nothing.
+ *
+ * Backends shell out to the OS tool — no native dependency, so the package
+ * stays zero-dep:
+ *  - Linux: `secret-tool` (libsecret) — reads the secret from STDIN (no argv leak).
+ *  - macOS: `security` — `add-generic-password` only accepts the secret via the
+ *    `-w` argv flag, so it is briefly visible to same-user `ps` during the call.
+ *    That transient, same-user exposure is strictly smaller than a persistent
+ *    plaintext file (which the same processes can read at any time), but it is a
+ *    real caveat, documented in SECURITY.md.
+ *
+ * Keychain entries are NOT scoped by $FSGTM_HOME (the OS store is machine-wide),
+ * so the account name is derived from the credential file path to keep distinct
+ * homes/profiles from colliding. This is also why keychain is opt-in: defaulting
+ * it on would make throwaway-home test/eval runs write to the machine keychain.
+ */
+export type KeychainBackend = {
+    readonly name: string;
+    get(account: string): string | null;
+    set(account: string, secret: string): void;
+    delete(account: string): void;
+};
+/** Test seam: force a backend (or null to force "none"). undefined = re-detect. */
+export declare function setKeychainBackendForTests(backend: KeychainBackend | null | undefined): void;
+/** The active backend for this platform, or null if none is available. */
+export declare function detectKeychainBackend(): KeychainBackend | null;

package/dist/keychain.js

@@ -0,0 +1,85 @@
+import { execFileSync } from "node:child_process";
+import { platform } from "node:os";
+const SERVICE = "fullstackgtm";
+function hasBinary(bin) {
+    try {
+        execFileSync("/usr/bin/env", ["which", bin], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const macosBackend = {
+    name: "macos-keychain",
+    get(account) {
+        try {
+            return execFileSync("security", ["find-generic-password", "-s", SERVICE, "-a", account, "-w"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).replace(/\n$/, "");
+        }
+        catch {
+            return null; // not found → non-zero exit
+        }
+    },
+    set(account, secret) {
+        // -U updates if present. NOTE: the secret is in argv for the duration of
+        // this call (see the module comment); `security` has no stdin path.
+        execFileSync("security", ["add-generic-password", "-U", "-s", SERVICE, "-a", account, "-w", secret], {
+            stdio: "ignore",
+        });
+    },
+    delete(account) {
+        try {
+            execFileSync("security", ["delete-generic-password", "-s", SERVICE, "-a", account], { stdio: "ignore" });
+        }
+        catch {
+            // already absent
+        }
+    },
+};
+const secretToolBackend = {
+    name: "linux-secret-tool",
+    get(account) {
+        try {
+            return execFileSync("secret-tool", ["lookup", "service", SERVICE, "account", account], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        catch {
+            return null;
+        }
+    },
+    set(account, secret) {
+        // secret-tool reads the secret from STDIN — no argv exposure.
+        execFileSync("secret-tool", ["store", "--label", `${SERVICE} ${account}`, "service", SERVICE, "account", account], {
+            input: secret,
+            stdio: ["pipe", "ignore", "ignore"],
+        });
+    },
+    delete(account) {
+        try {
+            execFileSync("secret-tool", ["clear", "service", SERVICE, "account", account], { stdio: "ignore" });
+        }
+        catch {
+            // already absent
+        }
+    },
+};
+let override;
+/** Test seam: force a backend (or null to force "none"). undefined = re-detect. */
+export function setKeychainBackendForTests(backend) {
+    override = backend;
+}
+/** The active backend for this platform, or null if none is available. */
+export function detectKeychainBackend() {
+    if (override !== undefined)
+        return override;
+    if (platform() === "darwin" && hasBinary("security"))
+        return macosBackend;
+    if (platform() === "linux" && hasBinary("secret-tool"))
+        return secretToolBackend;
+    return null;
+}

package/dist/llm.js

@@ -70,8 +70,23 @@ export async function extractInsightsLlm(transcript, options) {
     const text = truncateTranscript(transcript);
     const prompt = `${EXTRACT_INSTRUCTIONS}\n\n${options.title ? `Call: ${options.title}\n` : ""}Transcript:\n${text}`;
     const result = (await forcedToolCall(prompt, "extract_call_insights", EXTRACT_SCHEMA, model, options));
+    const normalizedTranscript = normalizeSpan(text);
     const insights = (result.insights ?? [])
         .filter((insight) => INSIGHT_TYPES.includes(insight.type))
+        // Mechanical verbatim gate (mirrors market classify): the prompt asks for a
+        // verbatim quote, but a prompt-injected or hallucinated transcript could
+        // fabricate a grounded-looking insight that drives a governed writeback.
+        // (1) The evidence quote must be a non-trivial verbatim span of the transcript.
+        .filter((insight) => {
+        const quote = normalizeSpan(insight.evidence ?? "");
+        return quote.length >= 12 && normalizedTranscript.includes(quote);
+    })
+        // (2) For next_step — the only insight type whose `text` is WRITTEN to the CRM
+        // (set_field nextStep / create_task body) — the written action must itself be
+        // grounded in the verified quote, not just accompanied by an innocuous one.
+        // This closes the decoupling attack: a prompt-injected transcript that emits a
+        // malicious `text` while quoting an unrelated real span no longer survives.
+        .filter((insight) => insight.type !== "next_step" || actionGroundedInEvidence(insight.text, insight.evidence ?? ""))
         .map((insight) => ({
         ...insight,
         title: insight.type.replace(/_/g, " "),
@@ -81,6 +96,39 @@ export async function extractInsightsLlm(transcript, options) {
         .sort((a, b) => b.importance - a.importance || b.confidence - a.confidence);
     return { insights, model };
 }
+/** Whitespace/punctuation-spacing-normalized match (same rule as market spans). */
+function normalizeSpan(value) {
+    return value
+        .replace(/\s+([.,;:!?])/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Is the written next-step action grounded in its (already transcript-verified)
+ * evidence quote? A legitimate next step paraphrases the quote, so it reuses the
+ * quote's salient terms; a prompt-injected action ("wire $50,000 to account
+ * 1234") quoting an unrelated innocuous span does not. Two checks: every
+ * number/amount in the action must appear in the evidence (defeats the
+ * financial-exfil class cleanly), and a meaningful share of the action's
+ * distinctive (≥4-char) words must appear in the evidence.
+ */
+function actionGroundedInEvidence(text, evidence) {
+    const action = normalizeSpan(text);
+    const quote = normalizeSpan(evidence);
+    if (!action)
+        return false;
+    const numbers = action.match(/\d[\d,.]*/g) ?? [];
+    for (const n of numbers) {
+        if (!quote.includes(n))
+            return false; // an ungrounded amount/account/id is a red flag
+    }
+    const distinctive = [...new Set(action.split(/[^a-z0-9$]+/).filter((token) => token.length >= 4))];
+    if (distinctive.length === 0)
+        return true; // nothing distinctive to ground (a short generic step)
+    const grounded = distinctive.filter((token) => quote.includes(token)).length;
+    return grounded / distinctive.length >= 0.4;
+}
 export const DEFAULT_RUBRIC = {
     scale: 5,
     dimensions: [

package/dist/mcp.js

@@ -23,8 +23,15 @@ async function importPeer(specifier) {
     }
     catch (error) {
         try {
+            // Last-resort fallback to the invoking project's node_modules (the npx
+            // landmine: peers there, fullstackgtm in the npx cache). This loads code
+            // from the current working directory, so make it VISIBLE — running the
+            // MCP server in an untrusted directory could otherwise silently load a
+            // malicious `zod`/SDK from its node_modules.
             const projectRequire = createRequire(join(process.cwd(), "package.json"));
-            return (await import(__rewriteRelativeImportExtension(pathToFileURL(projectRequire.resolve(specifier)).href)));
+            const resolved = projectRequire.resolve(specifier);
+            console.error(`fullstackgtm-mcp: loading peer "${specifier}" from the current directory (${resolved}). Only run the MCP server in a directory you trust.`);
+            return (await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href)));
         }
         catch {
             throw error; // the original error carries the missing-peer signal mcp-bin reports on

package/dist/types.d.ts

@@ -281,6 +281,12 @@ export type PatchPlan = {
     filter?: {
         objectType: "account" | "contact" | "deal";
         where: string[];
+        /**
+         * The date the filter's comparison `today` literal resolves to (ISO
+         * yyyy-mm-dd). Stored so apply-time re-verification resolves `today`
+         * identically to plan time; absent on plans built before comparison ops.
+         */
+        today?: string;
     };
     /**
      * Plan-level guards re-evaluated against a FRESH snapshot at apply time.

package/docs/api.md

@@ -91,8 +91,11 @@ emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
 
 - `buildBulkUpdatePlan(snapshot, options: BulkUpdateOptions)` with
   `parseWhere` (filter expressions: `=`, `!=`, `~`, `!~`, `:empty`,
-  `:notempty`, `|` any-of, relational pseudo-fields) and
-  `isFilterableField`. Filters are re-verified per record at apply time;
+  `:notempty`, type-aware comparisons `<`, `>`, `<=`, `>=` — `today` resolves
+  to `options.today`/the policy date, date and numeric fields coerce by value
+  form, `|` any-of, relational pseudo-fields) and `isFilterableField`. Filters
+  are re-verified per record at apply time (the resolved `today` rides along on
+  `plan.filter.today` so re-verification agrees with plan time);
   `from:<sourceField>` values derive per record from the snapshot.
 - `buildDedupePlan(snapshot, options: DedupeOptions)` with `dedupeKey` —
   duplicate groups by normalized identity key, one `merge_records` per group,

package/llms.txt

@@ -61,7 +61,13 @@ Storage is profile-scoped under `<home>/market/<category>`. MCP:
 snapshot into a dry-run plan; the FULL filter is re-verified per record at
 apply time (plus mid-apply rechecks); equality filters double as
 preconditions, `--require`/`--guard` add explicit ones, `--max-operations`
-caps blast radius. `--set f=from:<source>` derives per-record values (empty
+caps blast radius. Filter operators: `=` `!=` `~` `!~` `:empty` `:notempty`,
+plus type-aware comparisons `<` `>` `<=` `>=` (`today` resolves to the policy
+date, e.g. `closeDate<today`; date fields compare as dates, numeric as
+numbers, unset/non-parseable values do not match). For date/count hygiene
+(past close dates, stale deals, missing accounts, duplicates) prefer the
+rule-backed `fix --rule <id>` — it encodes the date/open-deal logic
+deterministically; reach for bulk-update only when no rule covers the task. `--set f=from:<source>` derives per-record values (empty
 source = skip + count, never guess). `--archive` refuses records sharing an
 identity key — merge with `dedupe` instead. `dedupe <object> --key
 <domain|email|name>` = one merge_records op per duplicate group,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "fullstackgtm",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
-  "author": "Full Stack GTM",
+  "author": "Full Stack GTM <security@fullstackgtm.com> (https://fullstackgtm.com)",
   "homepage": "https://github.com/fullstackgtm/core#readme",
   "bugs": {
     "url": "https://github.com/fullstackgtm/core/issues"
@@ -31,10 +31,13 @@
     "INSTALL_FOR_AGENTS.md",
     "llms.txt",
     "skills",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md",
+    "DATA-FLOWS.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "prepublishOnly": "npm run build"
   },

package/src/auditLog.ts

@@ -0,0 +1,173 @@
+import { createHash, createHmac } from "node:crypto";
+import { loadOrCreateSigningKey, loadSigningKey } from "./integrity.ts";
+import type { PatchPlanRun } from "./types.ts";
+import type { StoredPlan } from "./planStore.ts";
+
+/**
+ * Exportable, tamper-evident audit log.
+ *
+ * Every apply run is already recorded per-plan in the store, but a compliance /
+ * change-management process needs ONE portable artifact it can archive and
+ * later prove was not edited. `audit-log export` flattens every run across all
+ * plans into a hash-chained sequence: each entry carries the hash of the
+ * previous entry, so removing, reordering, or editing any entry breaks the
+ * chain at that point and `audit-log verify` reports exactly where. When a
+ * per-install signing key exists, the chain head is also HMAC-signed, so the
+ * export can be attributed to this installation, not just shown internally
+ * consistent.
+ *
+ * This is a point-in-time attestation of the stored run history; it is not a
+ * real-time append-only journal (that is future work). It answers "give me an
+ * auditable record of every change this tool applied, that my auditor can
+ * verify hasn't been doctored."
+ */
+
+export type AuditLogEntry = {
+  seq: number;
+  planId: string;
+  planTitle: string;
+  provider: string;
+  startedAt: string;
+  finishedAt: string;
+  status: PatchPlanRun["status"];
+  trigger: string;
+  /** operationId → status, the per-operation outcome of this run */
+  operations: Array<{ operationId: string; status: string; detail?: string }>;
+  prevHash: string;
+  hash: string;
+};
+
+export type AuditLogExport = {
+  version: 1;
+  generatedAt: string;
+  entryCount: number;
+  chainHead: string;
+  /** HMAC of chainHead with the per-install key, or null when no key exists. */
+  signature: string | null;
+  entries: AuditLogEntry[];
+};
+
+const GENESIS = "0".repeat(64);
+
+/** The content that the chain hash covers — everything but prevHash/hash. */
+function entryContent(entry: Omit<AuditLogEntry, "prevHash" | "hash">): string {
+  return JSON.stringify([
+    entry.seq,
+    entry.planId,
+    entry.planTitle,
+    entry.provider,
+    entry.startedAt,
+    entry.finishedAt,
+    entry.status,
+    entry.trigger,
+    entry.operations,
+  ]);
+}
+
+function chainHash(prevHash: string, content: string): string {
+  return createHash("sha256").update(prevHash).update("\n").update(content).digest("hex");
+}
+
+/** Flatten all runs from the stored plans, oldest first, into chained entries. */
+export function buildAuditLog(plans: StoredPlan[], generatedAt: string): AuditLogExport {
+  const runs: Array<{ stored: StoredPlan; run: PatchPlanRun }> = [];
+  for (const stored of plans) {
+    for (const run of stored.runs ?? []) runs.push({ stored, run });
+  }
+  runs.sort((a, b) => a.run.finishedAt.localeCompare(b.run.finishedAt));
+
+  const entries: AuditLogEntry[] = [];
+  let prevHash = GENESIS;
+  runs.forEach(({ stored, run }, index) => {
+    const base = {
+      seq: index,
+      planId: run.planId,
+      planTitle: stored.plan.title,
+      provider: run.provider,
+      startedAt: run.startedAt,
+      finishedAt: run.finishedAt,
+      status: run.status,
+      trigger: (run as { trigger?: string }).trigger ?? "manual",
+      operations: run.results.map((result) => ({
+        operationId: result.operationId,
+        status: result.status,
+        ...(result.detail ? { detail: result.detail } : {}),
+      })),
+    };
+    const hash = chainHash(prevHash, entryContent(base));
+    entries.push({ ...base, prevHash, hash });
+    prevHash = hash;
+  });
+
+  // Always sign — an unsigned export's keyless sha256 chain is self-recomputable
+  // (an attacker can edit entries and rebuild the chain from the public genesis),
+  // so the per-install HMAC is the only real tamper barrier. Bind the header
+  // fields into the signed material so metadata can't be altered either.
+  const key = loadOrCreateSigningKey();
+  const entryCount = entries.length;
+  return {
+    version: 1,
+    generatedAt,
+    entryCount,
+    chainHead: prevHash,
+    signature: signHead(key, 1, generatedAt, entryCount, prevHash),
+    entries,
+  };
+}
+
+function signHead(key: Buffer, version: number, generatedAt: string, entryCount: number, chainHead: string): string {
+  return createHmac("sha256", key).update(JSON.stringify([version, generatedAt, entryCount, chainHead])).digest("hex");
+}
+
+export type AuditLogVerification = {
+  ok: boolean;
+  /** seq of the first entry whose hash does not verify, or null if the chain holds */
+  brokenAt: number | null;
+  signatureOk: boolean | null; // null = no signature present / no key to check
+  detail: string;
+};
+
+/** Recompute the chain (and the signature if a key is available). */
+export function verifyAuditLog(log: AuditLogExport): AuditLogVerification {
+  let prevHash = GENESIS;
+  for (const entry of log.entries) {
+    if (entry.prevHash !== prevHash) {
+      return { ok: false, brokenAt: entry.seq, signatureOk: null, detail: `Chain breaks at entry ${entry.seq}: prevHash does not match the previous entry's hash (an entry was removed, reordered, or edited).` };
+    }
+    const expected = chainHash(prevHash, entryContent(entry));
+    if (expected !== entry.hash) {
+      return { ok: false, brokenAt: entry.seq, signatureOk: null, detail: `Chain breaks at entry ${entry.seq}: its content was edited after export (hash mismatch).` };
+    }
+    prevHash = entry.hash;
+  }
+  if (prevHash !== log.chainHead) {
+    return { ok: false, brokenAt: log.entries.length, signatureOk: null, detail: "The recorded chainHead does not match the recomputed chain." };
+  }
+  // The keyless chain alone is self-recomputable, so a missing/stripped signature
+  // means the export is forgeable — refuse it. (Current exports are always
+  // signed; a null signature is an old/unsigned or a downgraded export.)
+  if (!log.signature) {
+    return {
+      ok: false,
+      brokenAt: null,
+      signatureOk: false,
+      detail: "Unsigned export: the hash chain alone is self-recomputable, so this log cannot be trusted (the signature is absent or was stripped). Re-export on the issuing install.",
+    };
+  }
+  const key = loadSigningKey();
+  if (!key) {
+    // A third party without the issuing install's key cannot verify attribution.
+    // The chain is internally consistent, but that is not proof of authenticity.
+    return {
+      ok: false,
+      brokenAt: null,
+      signatureOk: null,
+      detail: "Chain is internally consistent, but this machine has no signing key to verify the signature — authenticity is unattributed. Verify on the issuing install.",
+    };
+  }
+  const signatureOk = signHead(key, log.version, log.generatedAt, log.entryCount, prevHash) === log.signature;
+  if (!signatureOk) {
+    return { ok: false, brokenAt: null, signatureOk: false, detail: "Signature does not match this installation's key — the log was exported elsewhere, or its entries/metadata were altered after signing." };
+  }
+  return { ok: true, brokenAt: null, signatureOk: true, detail: `Verified ${log.entries.length} entries; chain intact and signature valid.` };
+}