@usegraft/mdx-safety 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @usegraft/mdx-safety
+
+> Refuse executable MDX before it is stored or rendered.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Why
+
+MDX is code. `{expr}` evaluates JavaScript, `import` pulls modules in, and `@mdx-js/mdx`'s `run()` evaluates the compiled body with `new Function` in the host runtime, with full `process`, `fetch` and dynamic `import()`.
+
+For content an operator wrote and reviewed in git, that is the feature. It stops being the feature the moment someone else can author a page: on shared infrastructure, one author's body reaches every other tenant.
+
+## Install
+
+```bash
+npm i @usegraft/mdx-safety
+```
+
+## Use
+
+```ts
+import { assertSafeMdx, findExecutableMdx, type MdxTrust } from "@usegraft/mdx-safety";
+
+// throw, with every offender named at once
+assertSafeMdx(body, { label: "pages/home" });
+
+// or collect them yourself
+const found = findExecutableMdx(body);
+```
+
+Prose, GFM and components with literal attributes are unaffected. Expressions, `import`, `export`, expression-valued attributes and `{...spread}` attributes are refused.
+
+Source the checker cannot parse throws `UncheckableMdxError` rather than passing. That is deliberate: the renderer's parser is not this one, and the gap between two independently configured parsers is exactly where executable source would hide.
+
+## Not a sanitiser
+
+This refuses _executable_ constructs. It is not a general HTML sanitiser. If you render content from people you do not trust at all, put a sanitiser in front of it as well.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/feat/core/packages/mdx-safety/CHANGELOG.md) · [Security policy](https://github.com/AndersonDesign1/graft/blob/feat/core/SECURITY.md)

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/** One executable construct found in a body, with where it was. */
+interface ExecutableNode {
+    /** What it is, in the reader's terms rather than the AST's. */
+    kind: "expression" | "import-or-export" | "attribute-expression" | "attribute-spread" | "scripting-element" | "event-handler";
+    /** 1-based line, when the parser knew it. */
+    line?: number;
+    /** The offending source, truncated. */
+    snippet?: string;
+}
+/** Thrown when the checker cannot parse a body, so it cannot vouch for it. */
+declare class UncheckableMdxError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * Every executable construct in an MDX body, in source order.
+ *
+ * Returns them rather than throwing so a caller can report all of them at once
+ * — an author fixing one at a time learns the rule slowly and resents it.
+ *
+ * Source the checker cannot parse throws {@link UncheckableMdxError}. It used
+ * to return `[]` on the reasoning that "a body that will not parse cannot
+ * execute either" — which only holds if this parser understands at least as
+ * much as the one that renders. Two independently-configured parsers WILL
+ * drift, and the failure mode of that shortcut is to wave through exactly the
+ * source that sits in the gap. Refusing what we cannot read is the only
+ * direction that stays safe when they diverge.
+ */
+declare function findExecutableMdx(source: string): ExecutableNode[];
+/**
+ * How much of MDX a body is allowed to be.
+ *
+ * `"restricted"` refuses executable constructs. `"full"` accepts them, and is
+ * only correct where every author has commit access, because rendering
+ * evaluates `{…}` and `import` as JavaScript on the server. The name is
+ * declared here so the compiler, the SDKs and `graft.config.ts` all mean the
+ * same thing by it.
+ */
+type MdxTrust = "restricted" | "full";
+interface AssertSafeMdxOptions {
+    /** What is being checked, for the error message (e.g. "pages/home"). */
+    label?: string;
+}
+/**
+ * Throw unless the body is free of executable constructs.
+ *
+ * Called on the surfaces that accept content from someone who is not the
+ * operator — MCP `write_content`, Studio document saves.
+ *
+ * Content already in git is checked too, by `graft compile` via
+ * {@link findExecutableMdx}, unless the project sets `mdxTrust = "full"`. That
+ * setting is what "code review is the control" looks like when a project
+ * actually claims it. Compile checks because `MdxBody` refuses executable
+ * bodies at render by default, so an unchecked tree fails per-request in
+ * production instead of at build time.
+ */
+declare function assertSafeMdx(source: string, options?: AssertSafeMdxOptions): void;
+
+export { type AssertSafeMdxOptions, type ExecutableNode, type MdxTrust, UncheckableMdxError, assertSafeMdx, findExecutableMdx };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/index.ts
+import { GraftError } from "@usegraft/contracts";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+var KIND_LABEL = {
+  expression: "a `{\u2026}` expression",
+  "import-or-export": "an `import` or `export`",
+  "attribute-expression": "an attribute whose value is a `{\u2026}` expression",
+  "attribute-spread": "a `{...spread}` attribute",
+  "scripting-element": "an element that can load or run code",
+  "event-handler": "an inline event-handler attribute"
+};
+var SCRIPTING_ELEMENTS = /* @__PURE__ */ new Set([
+  "script",
+  "iframe",
+  "object",
+  "embed",
+  "frame",
+  "frameset",
+  "base"
+]);
+var EVENT_HANDLER_RE = /^on[a-z]/i;
+function snippetOf(value) {
+  if (typeof value !== "string" || value.length === 0) return void 0;
+  const flat = value.replace(/\s+/g, " ").trim();
+  return flat.length > 80 ? `${flat.slice(0, 77)}\u2026` : flat;
+}
+var processor = unified().use(remarkParse).use(remarkGfm).use(remarkMdx);
+var UncheckableMdxError = class extends Error {
+  constructor(cause) {
+    super("MDX could not be parsed for safety checking");
+    this.cause = cause;
+    this.name = "UncheckableMdxError";
+  }
+  cause;
+};
+function findExecutableMdx(source) {
+  let tree;
+  try {
+    tree = processor.parse(source);
+  } catch (error) {
+    throw new UncheckableMdxError(error);
+  }
+  const found = [];
+  const at = (node) => node.position?.start?.line;
+  visit(tree, (node) => {
+    if (node.type === "mdxFlowExpression" || node.type === "mdxTextExpression") {
+      found.push({ kind: "expression", line: at(node), snippet: snippetOf(node.value) });
+      return;
+    }
+    if (node.type === "mdxjsEsm") {
+      found.push({ kind: "import-or-export", line: at(node), snippet: snippetOf(node.value) });
+      return;
+    }
+    if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
+      const tag = node.name;
+      if (typeof tag === "string" && SCRIPTING_ELEMENTS.has(tag.toLowerCase())) {
+        found.push({ kind: "scripting-element", line: at(node), snippet: `<${tag}>` });
+      }
+      for (const attribute of node.attributes ?? []) {
+        if (attribute.type === "mdxJsxExpressionAttribute") {
+          found.push({
+            kind: "attribute-spread",
+            line: at(node),
+            snippet: snippetOf(attribute.value)
+          });
+          continue;
+        }
+        if (typeof attribute.name === "string" && EVENT_HANDLER_RE.test(attribute.name)) {
+          found.push({
+            kind: "event-handler",
+            line: at(node),
+            snippet: snippetOf(attribute.name)
+          });
+          continue;
+        }
+        const value = attribute.value;
+        if (value !== null && typeof value === "object" && value.type === "mdxJsxAttributeValueExpression") {
+          found.push({
+            kind: "attribute-expression",
+            line: at(node),
+            snippet: snippetOf(attribute.name)
+          });
+        }
+      }
+    }
+  });
+  return found;
+}
+function assertSafeMdx(source, options = {}) {
+  const found = findExecutableMdx(source);
+  if (found.length === 0) return;
+  const where = options.label ? ` in ${options.label}` : "";
+  const listed = found.slice(0, 5).map((node) => {
+    const line = node.line === void 0 ? "" : ` (line ${node.line})`;
+    const snippet = node.snippet === void 0 ? "" : `: ${node.snippet}`;
+    return `${KIND_LABEL[node.kind]}${line}${snippet}`;
+  }).join("; ");
+  const more = found.length > 5 ? ` \u2026and ${found.length - 5} more` : "";
+  throw new GraftError({
+    code: "INPUT_VALIDATION_FAILED",
+    message: `Executable MDX is not accepted${where} \u2014 found ${listed}${more}.`,
+    fix: "Write prose, Markdown and components with literal attributes. `{\u2026}` expressions, `import`, `export` and spread attributes are refused because rendering evaluates them as JavaScript on the server. If this content is operator-authored and needs full MDX, commit it to the repository instead, where code review is the control.",
+    details: { found: found.length, nodes: found.slice(0, 20) }
+  });
+}
+export {
+  UncheckableMdxError,
+  assertSafeMdx,
+  findExecutableMdx
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@usegraft/mdx-safety",
+  "version": "0.2.0",
+  "description": "Refuse executable MDX before it is stored or rendered. MDX is code, and rendering evaluates it on the server.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cms",
+    "content-security",
+    "graft",
+    "headless-cms",
+    "mcp",
+    "mdx",
+    "sandbox",
+    "security",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/mdx-safety"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@usegraft/contracts": "0.2.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}