@rubytech/create-maxy 1.0.743 → 1.0.745

package/payload/platform/lib/graph-mcp/src/cypher-shim-write.ts

@@ -0,0 +1,240 @@
+/**
+ * Pure helpers for the shim-owned write_neo4j_cypher path (Task 797).
+ * Extracted from index.ts so the executeWrite tx body, response synthesis,
+ * and value serialization can be unit-tested without the shim's top-level
+ * process bootstrap (which spawns uvx and opens stdin/stdout pipes).
+ *
+ * The shim's index.ts wires these up: rewriter → shared driver → session.
+ * executeWrite(tx => runWriteTxBody(...)) → response synth → stdout.
+ */
+
+export const ORPHAN_CHECK_CYPHER =
+  "MATCH (n) WHERE n.createdBySession = $__autoSession " +
+  "AND n.createdAt >= $__autoStartTimestamp " +
+  "AND NOT (n)--() " +
+  "RETURN collect(elementId(n)) AS orphanIds, " +
+  "collect(distinct labels(n)) AS labelSets";
+
+export interface GraphTx {
+  run(
+    cypher: string,
+    params?: Record<string, unknown>,
+  ): Promise<{
+    records: Array<{
+      keys: readonly string[];
+      get: (k: string | number) => unknown;
+    }>;
+    summary: {
+      counters: {
+        updates(): {
+          nodesCreated: number;
+          relationshipsCreated: number;
+          propertiesSet: number;
+        };
+      };
+    };
+  }>;
+}
+
+export interface GraphSession {
+  executeWrite<T>(work: (tx: GraphTx) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+}
+
+export interface GraphDriver {
+  session(): GraphSession;
+}
+
+export class OrphanRollbackError extends Error {
+  constructor(
+    public readonly orphanIds: string[],
+    public readonly sampleLabels: string[],
+  ) {
+    super(`orphan rollback: ${orphanIds.length} unattached node(s)`);
+  }
+}
+
+export interface AutoContext {
+  agent: string;
+  session: string;
+}
+
+export interface WriteTxOutcome {
+  nodesCreated: number;
+  relsCreated: number;
+  propertiesSet: number;
+  serializedRecords: Array<Record<string, unknown>>;
+}
+
+export function serializeValue(v: unknown): unknown {
+  if (v === null || v === undefined) return v;
+  if (typeof v === "string" || typeof v === "boolean" || typeof v === "number") {
+    return v;
+  }
+  if (Array.isArray(v)) return v.map(serializeValue);
+  if (typeof v === "object") {
+    const obj = v as Record<string, unknown>;
+    if (
+      "low" in obj &&
+      "high" in obj &&
+      typeof obj.low === "number" &&
+      typeof obj.high === "number" &&
+      Object.keys(obj).length === 2
+    ) {
+      if (obj.high === 0 || obj.high === -1) return obj.low;
+      return String(obj);
+    }
+    if ("properties" in obj && "labels" in obj) {
+      return {
+        labels: obj.labels,
+        elementId: obj.elementId,
+        properties: serializeValue(obj.properties),
+      };
+    }
+    if ("properties" in obj && "type" in obj && "elementId" in obj) {
+      return {
+        type: obj.type,
+        elementId: obj.elementId,
+        properties: serializeValue(obj.properties),
+      };
+    }
+    if (
+      obj.constructor &&
+      obj.constructor.name &&
+      obj.constructor.name !== "Object" &&
+      obj.constructor.name !== "Array"
+    ) {
+      return String(obj);
+    }
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(obj)) {
+      out[k] = serializeValue(val);
+    }
+    return out;
+  }
+  return v;
+}
+
+/**
+ * Body of the executeWrite tx. Runs the rewritten cypher, captures counters,
+ * runs the orphan check, throws OrphanRollbackError if any orphans remain
+ * (executeWrite catches the throw and rolls back the entire tx).
+ *
+ * Caller is responsible for: (a) opening the session, (b) wrapping this in
+ * `session.executeWrite(tx => runWriteTxBody(tx, ...))`, (c) calling close()
+ * in finally, (d) translating the outcome / OrphanRollbackError into the
+ * synthesised MCP response and audit log lines.
+ */
+export async function runWriteTxBody(
+  tx: GraphTx,
+  rewrittenCypher: string,
+  operatorParams: Record<string, unknown>,
+  autoCtx: AutoContext,
+): Promise<WriteTxOutcome> {
+  const tsRes = await tx.run("RETURN datetime() AS now");
+  const startTs = tsRes.records[0].get("now");
+
+  const merged: Record<string, unknown> = {
+    ...operatorParams,
+    __autoStartTimestamp: startTs,
+    __autoAgent: autoCtx.agent,
+    __autoSession: autoCtx.session,
+  };
+
+  const writeRes = await tx.run(rewrittenCypher, merged);
+  const counters = writeRes.summary.counters.updates();
+  const nodesCreated = counters.nodesCreated;
+  const relsCreated = counters.relationshipsCreated;
+  const propertiesSet = counters.propertiesSet;
+  const keys =
+    writeRes.records.length > 0 ? writeRes.records[0].keys.map(String) : [];
+  const serializedRecords = writeRes.records.map((rec) => {
+    const out: Record<string, unknown> = {};
+    for (const k of keys) {
+      out[k] = serializeValue(rec.get(k));
+    }
+    return out;
+  });
+
+  const orphanRes = await tx.run(ORPHAN_CHECK_CYPHER, merged);
+  const orphanIds = (orphanRes.records[0].get("orphanIds") as string[]) ?? [];
+  const labelSets =
+    (orphanRes.records[0].get("labelSets") as string[][]) ?? [];
+  if (orphanIds.length > 0) {
+    const flatLabels = Array.from(new Set(labelSets.flat()));
+    throw new OrphanRollbackError(orphanIds, flatLabels);
+  }
+
+  return { nodesCreated, relsCreated, propertiesSet, serializedRecords };
+}
+
+export interface WriteSynthInput {
+  nodesCreated: number;
+  relsCreated: number;
+  propertiesSet: number;
+  records: Array<Record<string, unknown>>;
+}
+
+export function synthesiseWriteResponse(
+  id: string | number,
+  w: WriteSynthInput,
+): string {
+  const parts: string[] = [];
+  if (w.records.length > 0) {
+    parts.push(
+      `${w.records.length} record${w.records.length === 1 ? "" : "s"} returned`,
+    );
+  }
+  parts.push(`${w.nodesCreated} nodes created`);
+  parts.push(`${w.relsCreated} relationships created`);
+  if (w.propertiesSet > 0) parts.push(`${w.propertiesSet} properties set`);
+  if (w.records.length > 0) {
+    parts.push("");
+    parts.push(JSON.stringify(w.records, null, 2));
+  }
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text: parts.join("\n") }],
+    },
+  });
+}
+
+export function synthesiseOrphanRollback(
+  id: string | number,
+  orphanCount: number,
+  sampleLabels: string[],
+): string {
+  const labelLine =
+    sampleLabels.length > 0
+      ? sampleLabels.slice(0, 5).join(", ")
+      : "(unknown — orphans had no labels)";
+  const text =
+    `orphan rollback — ${orphanCount} node(s) created without an edge in the same transaction.\n` +
+    `Sample labels: ${labelLine}.\n\n` +
+    `The transaction was aborted; nothing was persisted. Anchor each new node to its semantic parent in the same statement (Graph Stewardship Doctrine Rule 1 in database-operator.md).`;
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text }],
+      isError: true,
+    },
+  });
+}
+
+export function synthesiseShimError(
+  id: string | number,
+  prefix: string,
+  errMsg: string,
+): string {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text: `${prefix}: ${errMsg}` }],
+      isError: true,
+    },
+  });
+}

package/payload/platform/lib/graph-mcp/src/cypher-validate.ts

@@ -31,13 +31,75 @@ export interface UnknownToken {
   hint: string;
 }
 
+export type ForbiddenKind =
+  | "drop-database"
+  | "create-index"
+  | "create-constraint"
+  | "call-dbms"
+  | "call-db-create";
+
+export interface ForbiddenPattern {
+  kind: ForbiddenKind;
+  match: string;
+  hint: string;
+}
+
 export interface ValidationResult {
   ok: boolean;
   unknown: UnknownToken[];
+  forbidden: ForbiddenPattern[];
   labelTokens: string[];
   edgeTokens: string[];
 }
 
+export interface ValidateOptions {
+  /** "read" (default) skips DDL/admin forbidden checks. "write" applies them. */
+  mode?: "read" | "write";
+}
+
+// DDL / admin patterns that the database-operator's raw write surface must
+// reject. The graph MCP shim is the only enforcement point — Neo4j Community
+// has no per-tool ACL, so the shim filters by syntactic shape before
+// forwarding the JSON-RPC line to the upstream cypher driver. Each pattern
+// is applied to a string-literal-stripped cypher body so that prose inside
+// quoted strings cannot trip a false positive.
+//
+// CALL apoc.* is intentionally NOT forbidden — apoc.refactor.mergeNodes is
+// the documented dedup primitive. CALL db.labels() and other read-only db.*
+// calls are allowed; only db.create* (createLabel, createProperty,
+// createRelationshipType) is forbidden because those are schema-mutating.
+const FORBIDDEN_PATTERNS: ReadonlyArray<{
+  kind: ForbiddenKind;
+  pattern: RegExp;
+  hint: string;
+}> = [
+  {
+    kind: "drop-database",
+    pattern: /\bDROP\s+(?:DATABASE|ALIAS|USER|ROLE)\b/i,
+    hint: "DROP DATABASE/USER/ROLE/ALIAS is admin DDL — not permitted on the operator surface.",
+  },
+  {
+    kind: "create-index",
+    pattern: /\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:RANGE\s+|TEXT\s+|POINT\s+|LOOKUP\s+|FULLTEXT\s+|BTREE\s+|VECTOR\s+)?INDEX\b/i,
+    hint: "Index DDL is admin-owned (seed-neo4j.sh applies indexes). Not permitted on the operator surface.",
+  },
+  {
+    kind: "create-constraint",
+    pattern: /\bCREATE\s+(?:OR\s+REPLACE\s+)?CONSTRAINT\b/i,
+    hint: "Constraint DDL is admin-owned (seed-neo4j.sh applies constraints). Not permitted on the operator surface.",
+  },
+  {
+    kind: "call-dbms",
+    pattern: /\bCALL\s+dbms\./i,
+    hint: "CALL dbms.* is admin/security surface. Not permitted on the operator surface.",
+  },
+  {
+    kind: "call-db-create",
+    pattern: /\bCALL\s+db\.create/i,
+    hint: "CALL db.create* mutates schema (label/property/type registration). Not permitted on the operator surface.",
+  },
+];
+
 // Bracket content containing a type reference. Examples this matches:
 //   [:PART_OF]
 //   [r:PART_OF]
@@ -52,7 +114,10 @@ const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[
 // the edge pattern. The [A-Z] anchor excludes lowercase map keys.
 const LABEL_PATTERN = /:([A-Z][A-Za-z0-9_]*)/g;
 
-function stripStringLiterals(cypher: string): string {
+// Exported so the post-write audit (graph-write/audit.ts) can reuse the same
+// literal-stripping pass before its own static parsing — avoids duplicate
+// false-positive treatment across the two surfaces.
+export function stripStringLiterals(cypher: string): string {
   // Replace single- and double-quoted literals with empty quotes. Preserves
   // positional structure without retaining content that could match the
   // label regex (e.g. ':SomeLabel' inside a string).
@@ -118,19 +183,40 @@ function hintFor(
   return `${didYouMean}Unknown ${kind} '${token}' — not in the current Neo4j schema. See .docs/neo4j.md for the canonical taxonomy.`;
 }
 
+function detectForbidden(cypher: string): ForbiddenPattern[] {
+  // Strip literals so a property value like 'CREATE INDEX archive' cannot
+  // trip a false rejection. The shared `stripStringLiterals` keeps this
+  // treatment uniform with token extraction and audit static parsing.
+  const cleaned = stripStringLiterals(cypher);
+  const out: ForbiddenPattern[] = [];
+  for (const { kind, pattern, hint } of FORBIDDEN_PATTERNS) {
+    const found = cleaned.match(pattern);
+    if (found) {
+      out.push({ kind, match: found[0], hint });
+    }
+  }
+  return out;
+}
+
 export function validate(
   cypher: string,
   snapshot: SchemaSnapshot,
+  options: ValidateOptions = {},
 ): ValidationResult {
+  const mode = options.mode ?? "read";
+  const forbidden = mode === "write" ? detectForbidden(cypher) : [];
   const { labels, edges } = extractTokens(cypher);
   // Fail-open when the snapshot is empty. An empty snapshot means "schema
   // cache not loaded" (boot race, Neo4j unreachable). Rejecting every token
   // would wedge the admin agent; letting it through preserves the observable
   // `validated=false` signal on the existing [graph-query] line.
+  // Forbidden DDL/admin patterns still apply — those are syntactic, not
+  // schema-derived.
   if (snapshot.labels.size === 0 && snapshot.relationshipTypes.size === 0) {
     return {
-      ok: true,
+      ok: forbidden.length === 0,
       unknown: [],
+      forbidden,
       labelTokens: [...labels],
       edgeTokens: [...edges],
     };
@@ -148,9 +234,15 @@ export function validate(
       unknown.push({ token, kind: "relationship", nearest, hint: hintFor(token, "relationship", nearest) });
     }
   }
+  // Write-mode caller treats `unknown` as a soft warning (audit), not a
+  // hard reject — operators legitimately introduce new labels via REMOVE
+  // n:Old SET n:New. Read-mode preserves prior behaviour: any unknown
+  // → ok=false.
+  const tokensOk = mode === "write" ? true : unknown.length === 0;
   return {
-    ok: unknown.length === 0,
+    ok: tokensOk && forbidden.length === 0,
     unknown,
+    forbidden,
     labelTokens: [...labels],
     edgeTokens: [...edges],
   };