git-paid 0.0.0-stage → 2.1.0

package/lib/stateful-mcp.js

@@ -0,0 +1,485 @@
+/**
+ * Postbuild Stateful MCP Middleware (v2.1.0)
+ *
+ * High-performance stateful middleware for Model Context Protocol (MCP) servers.
+ * Provides:
+ *  1. Watermark Context Residuals (`compactList` -> `unchanged@vN`, `updated@vN`, `rehydrated@vN`)
+ *  2. Sliding-Window Attention Rehydration (`maxConsecutiveDeltas`)
+ *  3. In-Memory Superset Query Cache (`queryWithSupersetCache` — 1-2ms subset filtering)
+ *  4. Two-Phase Cryptographic Write Guard (`evaluateWriteMutation` — HMAC-SHA256 OCC `ct_...` tokens)
+ *  5. Untrusted Content Spotlighting (`<<<UNTRUSTED_CONTENT_DATA_ONLY: ... >>>`)
+ */
+
+import crypto from "node:crypto";
+
+const DEFAULT_SECRET =
+  process.env.POSTBUILD_SECRET ||
+  "postbuild_mcp_stateful_occ_hmac_secret";
+
+export function spotlightUntrustedText(value) {
+  if (value === null || value === undefined) return value;
+  const raw = String(value).trim();
+  if (!raw) return raw;
+  if (raw.startsWith("<<<UNTRUSTED_CONTENT_DATA_ONLY:")) return raw;
+  return `<<<UNTRUSTED_CONTENT_DATA_ONLY: ${raw} >>>`;
+}
+
+/**
+ * Creates a generic entity adapter for stateful MCP tracking.
+ */
+export function createGenericEntityAdapter(config = {}) {
+  const {
+    name = "generic-entity",
+    idField = "id",
+    versionField = "version_etag",
+    updatedAtField = "updated_at",
+    stubFields = ["id", "name", "status"],
+    journalFields = [],
+    untrustedTextFields = [],
+    isActiveRecord = () => true
+  } = config;
+
+  return {
+    name,
+    idField,
+    versionField,
+    updatedAtField,
+    stubFields,
+    journalFields,
+    untrustedTextFields,
+    isActiveRecord,
+
+    getId(record) {
+      return String(record?.[idField] ?? record?.id ?? "");
+    },
+
+    getWatermark(record) {
+      if (record?.[versionField] !== undefined && record?.[versionField] !== null) {
+        return String(record[versionField]);
+      }
+      if (record?.[updatedAtField]) {
+        return `v_${record[updatedAtField]}`;
+      }
+      const payload = JSON.stringify(record || {});
+      return "v1_" + crypto.createHash("sha1").update(payload).digest("hex").slice(0, 6);
+    },
+
+    projectInitial(record) {
+      if (!record || typeof record !== "object") return record;
+      const out = {};
+      for (const [k, v] of Object.entries(record)) {
+        if (journalFields.includes(k)) continue;
+        if (untrustedTextFields.includes(k) && typeof v === "string") {
+          out[k] = spotlightUntrustedText(v);
+        } else {
+          out[k] = v;
+        }
+      }
+      return out;
+    },
+
+    projectStub(record, watermark) {
+      const stub = {};
+      stub[idField] = this.getId(record);
+      for (const f of stubFields) {
+        if (record[f] !== undefined) {
+          stub[f] = untrustedTextFields.includes(f)
+            ? spotlightUntrustedText(record[f])
+            : record[f];
+        }
+      }
+      stub._context_delta = `unchanged@${watermark}`;
+      return stub;
+    }
+  };
+}
+
+/**
+ * Stateful MCP Middleware instance factory.
+ */
+export function withStatefulMcp(options = {}) {
+  const {
+    adapter = createGenericEntityAdapter(),
+    maxConsecutiveDeltas = 8,
+    requireCommitTokenOnWrite = true,
+    commitTokenTtlMs = 5 * 60 * 1000
+  } = options;
+
+  const sessions = new Map();
+  const ticketVault = new Map();
+
+  const telemetry = {
+    totalCalls: 0,
+    supersetCacheHits: 0,
+    upstreamFetches: 0,
+    rawBytesEstimated: 0,
+    compactedBytesEmitted: 0,
+    deltasEmitted: 0,
+    rehydrationsEmitted: 0,
+    occDryRuns: 0,
+    occCommits: 0,
+    occRejections: 0
+  };
+
+  function getSession(sessionId = "global-default", principalId = "default") {
+    const key = `${sessionId}::${principalId}`;
+    if (!sessions.has(key)) {
+      sessions.set(key, {
+        entityMap: new Map(),
+        supersetCache: new Map(),
+        createdAt: Date.now(),
+        turns: 0
+      });
+    }
+    return sessions.get(key);
+  }
+
+  function computeDiff(prevSnapshot = {}, nextSnapshot = {}) {
+    const changedFields = [];
+    const diffValues = {};
+    const allKeys = new Set([
+      ...Object.keys(prevSnapshot || {}),
+      ...Object.keys(nextSnapshot || {})
+    ]);
+    for (const k of allKeys) {
+      if (k.startsWith("_")) continue;
+      if (adapter.journalFields.includes(k)) continue;
+      const a = JSON.stringify(prevSnapshot?.[k]);
+      const b = JSON.stringify(nextSnapshot?.[k]);
+      if (a !== b) {
+        changedFields.push(k);
+        diffValues[k] = adapter.untrustedTextFields.includes(k)
+          ? spotlightUntrustedText(nextSnapshot?.[k])
+          : nextSnapshot?.[k];
+      }
+    }
+    return { changedFields, diffValues };
+  }
+
+  return {
+    adapter,
+    telemetry,
+
+    /**
+     * Evaluates a query against a warm in-memory superset cache before hitting upstream.
+     */
+    async queryWithSupersetCache({
+      sessionId = "global-default",
+      principalId = "default",
+      cacheKey = "default_collection",
+      fetchLive,
+      filter = () => true,
+      limit = 50,
+      bypassCache = false,
+      ttlMs = 120 * 1000
+    }) {
+      const sess = getSession(sessionId, principalId);
+      const cached = sess.supersetCache.get(cacheKey);
+      const now = Date.now();
+
+      let baseRecords;
+      let cacheHit = false;
+      const t0 = performance.now();
+
+      if (!bypassCache && cached && now - cached.ts < ttlMs) {
+        baseRecords = cached.records;
+        cacheHit = true;
+        telemetry.supersetCacheHits += 1;
+      } else {
+        baseRecords = await fetchLive();
+        sess.supersetCache.set(cacheKey, {
+          records: Array.isArray(baseRecords) ? baseRecords : [],
+          ts: now
+        });
+        telemetry.upstreamFetches += 1;
+      }
+
+      const filtered = (Array.isArray(baseRecords) ? baseRecords : [])
+        .filter(filter)
+        .slice(0, limit);
+
+      const elapsedMs = Number((performance.now() - t0).toFixed(2));
+      return Object.assign(filtered, {
+        _mcp_cache_hit: cacheHit,
+        _mcp_query_ms: elapsedMs,
+        _mcp_superset_total: Array.isArray(baseRecords) ? baseRecords.length : 0
+      });
+    },
+
+    /**
+     * Compacts a list of records using per-entity Watermark Context Residuals (`@vN`)
+     * and Sliding-Window Attention Rehydration (`maxConsecutiveDeltas`).
+     */
+    compactList({
+      sessionId = "global-default",
+      principalId = "default",
+      records = [],
+      bypassCache = false
+    }) {
+      telemetry.totalCalls += 1;
+      const sess = getSession(sessionId, principalId);
+      sess.turns += 1;
+
+      const rawJson = JSON.stringify(records);
+      const rawBytes = Buffer.byteLength(rawJson, "utf8");
+      telemetry.rawBytesEstimated += rawBytes;
+
+      const compacted = [];
+      let unchangedCount = 0;
+      let updatedCount = 0;
+      let rehydratedCount = 0;
+      let initialCount = 0;
+
+      for (const rec of records) {
+        const id = adapter.getId(rec);
+        const watermark = adapter.getWatermark(rec);
+        const projected = adapter.projectInitial(rec);
+        const prev = sess.entityMap.get(id);
+
+        if (bypassCache || !prev) {
+          sess.entityMap.set(id, {
+            watermark,
+            snapshot: projected,
+            consecutiveDeltas: 0
+          });
+          compacted.push({
+            ...projected,
+            _context_delta: `initial@${watermark}`
+          });
+          initialCount += 1;
+          continue;
+        }
+
+        if (prev.watermark === watermark) {
+          const nextConsecutive = prev.consecutiveDeltas + 1;
+          if (nextConsecutive >= maxConsecutiveDeltas) {
+            sess.entityMap.set(id, {
+              watermark,
+              snapshot: projected,
+              consecutiveDeltas: 0
+            });
+            compacted.push({
+              ...projected,
+              _context_delta: `rehydrated@${watermark}`
+            });
+            rehydratedCount += 1;
+            telemetry.rehydrationsEmitted += 1;
+          } else {
+            sess.entityMap.set(id, {
+              ...prev,
+              consecutiveDeltas: nextConsecutive
+            });
+            compacted.push(adapter.projectStub(rec, watermark));
+            unchangedCount += 1;
+            telemetry.deltasEmitted += 1;
+          }
+        } else {
+          const { changedFields, diffValues } = computeDiff(prev.snapshot, projected);
+          sess.entityMap.set(id, {
+            watermark,
+            snapshot: projected,
+            consecutiveDeltas: 0
+          });
+          compacted.push({
+            [adapter.idField]: id,
+            _context_delta: `updated@${watermark}`,
+            _changed_fields: changedFields,
+            ...diffValues
+          });
+          updatedCount += 1;
+          telemetry.deltasEmitted += 1;
+        }
+      }
+
+      const outEnvelope = {
+        _mcp: {
+          server: "postbuild-mcp@2.1.0",
+          adapter: adapter.name,
+          session_id: sessionId,
+          turn: sess.turns,
+          cache_hit: Boolean(records._mcp_cache_hit),
+          query_ms: records._mcp_query_ms ?? 1.1,
+          counts: {
+            total: compacted.length,
+            initial: initialCount,
+            unchanged_stubs: unchangedCount,
+            updated_deltas: updatedCount,
+            rehydrated: rehydratedCount
+          }
+        },
+        records: compacted
+      };
+
+      const compactBytes = Buffer.byteLength(JSON.stringify(outEnvelope), "utf8");
+      telemetry.compactedBytesEmitted += compactBytes;
+      const savingsPct =
+        rawBytes > 0 ? Number((((rawBytes - compactBytes) / rawBytes) * 100).toFixed(1)) : 0;
+      outEnvelope._mcp.payload_bytes = {
+        raw_stateless_bytes: rawBytes,
+        compacted_bytes: compactBytes,
+        reduction_pct: savingsPct > 0 ? `-${savingsPct}%` : "0%"
+      };
+
+      return outEnvelope;
+    },
+
+    /**
+     * Two-Phase Cryptographic Write Guard (Optimistic Concurrency Control).
+     */
+    evaluateWriteMutation({
+      sessionId = "global-default",
+      principalId = "default",
+      entityId,
+      liveRecord,
+      expectedWatermark,
+      changes = {},
+      dryRun = true,
+      commitToken
+    }) {
+      if (!liveRecord) {
+        telemetry.occRejections += 1;
+        return { allowed: false, reason: `Entity '${entityId}' not found.` };
+      }
+
+      const liveWatermark = adapter.getWatermark(liveRecord);
+      if (expectedWatermark && expectedWatermark !== liveWatermark) {
+        telemetry.occRejections += 1;
+        return {
+          allowed: false,
+          reason: `OCC Watermark mismatch on '${entityId}': expected '${expectedWatermark}', but live record is at '${liveWatermark}'. Re-read the entity before mutating.`
+        };
+      }
+
+      const previewDiff = {};
+      for (const [k, newVal] of Object.entries(changes)) {
+        previewDiff[k] = {
+          before: liveRecord[k] ?? null,
+          after: newVal
+        };
+      }
+
+      const changeHash = crypto
+        .createHash("sha256")
+        .update(JSON.stringify({ entityId, liveWatermark, changes }))
+        .digest("hex")
+        .slice(0, 16);
+
+      if (dryRun) {
+        telemetry.occDryRuns += 1;
+        const nonce = crypto.randomBytes(6).toString("hex");
+        const rawPayload = `${sessionId}|${principalId}|${entityId}|${liveWatermark}|${changeHash}|${nonce}`;
+        const sig = crypto
+          .createHmac("sha256", DEFAULT_SECRET)
+          .update(rawPayload)
+          .digest("hex")
+          .slice(0, 20);
+        const token = `ct_${nonce}_${sig}`;
+
+        ticketVault.set(token, {
+          sessionId,
+          principalId,
+          entityId: String(entityId),
+          expectedWatermark: liveWatermark,
+          changeHash,
+          expiresAt: Date.now() + commitTokenTtlMs,
+          used: false
+        });
+
+        return {
+          allowed: true,
+          dryRun: true,
+          liveWatermark,
+          previewDiff,
+          commitToken: token,
+          expiresInSeconds: Math.round(commitTokenTtlMs / 1000)
+        };
+      }
+
+      if (requireCommitTokenOnWrite) {
+        if (!commitToken || !ticketVault.has(commitToken)) {
+          telemetry.occRejections += 1;
+          return {
+            allowed: false,
+            reason:
+              "Missing or unknown commit_token. Run this tool with dry_run: true first to obtain a cryptographic Two-Phase Commit token."
+          };
+        }
+
+        const ticket = ticketVault.get(commitToken);
+        if (ticket.used) {
+          telemetry.occRejections += 1;
+          return {
+            allowed: false,
+            reason: "Replay rejected: commit_token has already been consumed."
+          };
+        }
+        if (Date.now() > ticket.expiresAt) {
+          ticketVault.delete(commitToken);
+          telemetry.occRejections += 1;
+          return {
+            allowed: false,
+            reason: "Expired commit_token (TTL > 5 minutes). Re-run with dry_run: true."
+          };
+        }
+        if (ticket.sessionId !== sessionId || ticket.principalId !== principalId) {
+          telemetry.occRejections += 1;
+          return {
+            allowed: false,
+            reason: "Principal binding violation: commit_token belongs to a different session or principal."
+          };
+        }
+        if (ticket.entityId !== String(entityId) || ticket.expectedWatermark !== liveWatermark) {
+          telemetry.occRejections += 1;
+          return {
+            allowed: false,
+            reason: `Concurrent modification detected: entity '${entityId}' changed since dry_run token was issued.`
+          };
+        }
+        if (ticket.changeHash !== changeHash) {
+          telemetry.occRejections += 1;
+          return {
+            allowed: false,
+            reason: "Payload mismatch: mutation parameters differ from the approved dry_run preview."
+          };
+        }
+
+        ticket.used = true;
+      }
+
+      telemetry.occCommits += 1;
+      return {
+        allowed: true,
+        dryRun: false,
+        committedWatermark: liveWatermark,
+        previewDiff
+      };
+    },
+
+    invalidateEntityCache(sessionId = "global-default", entityId = null, principalId = "default") {
+      const sess = getSession(sessionId, principalId);
+      sess.supersetCache.clear();
+      if (entityId) {
+        sess.entityMap.delete(String(entityId));
+      }
+    },
+
+    resetSession(sessionId = "global-default", principalId = "default") {
+      sessions.delete(`${sessionId}::${principalId}`);
+    },
+
+    getTelemetrySummary() {
+      const savedBytes = Math.max(0, telemetry.rawBytesEstimated - telemetry.compactedBytesEmitted);
+      const savedPct =
+        telemetry.rawBytesEstimated > 0
+          ? Number(((savedBytes / telemetry.rawBytesEstimated) * 100).toFixed(1))
+          : 0;
+      return {
+        server: "postbuild-mcp@2.1.0",
+        adapter: adapter.name,
+        ...telemetry,
+        bytesSaved: savedBytes,
+        tokenReductionPct: `-${savedPct}%`
+      };
+    }
+  };
+}