canopycms 0.0.68-int.98 → 0.1.0

package/dist/validation/markdown-safety.js

@@ -0,0 +1,596 @@
+/**
+ * The save-time policy that keeps code out of `markdown` and `mdx` content.
+ *
+ * MDX compiles `{expressions}`, `import`/`export` and JSX into JavaScript that runs wherever a
+ * body renders: a preview with the viewer's session, a server render, a CI build. A body this
+ * policy accepts runs only the site's own components. A field or body `markdownPolicyOf` checks as
+ * MDX accepts:
+ *
+ * - no `import`/`export`, and no `{…}` expression except a comment or a static literal
+ *   (`{300}`, `{["a", "b"]}`), in text or as an attribute value; no spread attributes;
+ * - components by plain name (`<Callout>`, the site's own code) and HTML tags from
+ *   `SAFE_HTML_TAGS` only, since a tag is a real element whose attributes need no expression to
+ *   run code (`<script>`, `<iframe srcdoc>`);
+ * - on an HTML tag, attributes from `SAFE_HTML_ATTRIBUTES` and `aria-*` only; no event handler
+ *   (`on…` on a tag, `onX` on a component), `dangerouslySetInnerHTML` or `srcdoc` anywhere;
+ * - URLs, in links, images, definitions and URL attributes, that are relative, use a scheme in
+ *   `SAFE_URL_SCHEMES`, or are raster `data:` images; no `javascript:` or `vbscript:` value in any
+ *   prop. React 18 renders a `javascript:` href as given.
+ *
+ * An `mdxAllow` allowlist (`mdx-allowlist.ts`) narrows this further. Other markdown renders braces
+ * and imports as text and runs no tag without raw HTML, so only its URLs are checked; a field with
+ * `executable: true` is not checked. A body is parsed with and without GFM, so `remark-gfm` cannot
+ * hide a construct; an MDX body that does not parse cannot be checked, so is refused.
+ *
+ * A save keeps code the stored entry already holds (from outside the CMS, or from before this
+ * policy) only in a field saved unchanged: code reads what surrounds it (the props beside it, its
+ * parent, the markup a script reads), so no smaller unit is safe to keep. Other fields stay
+ * editable, and removing the code is always accepted.
+ */
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { gfmFromMarkdown } from 'mdast-util-gfm';
+import { mdxFromMarkdown } from 'mdast-util-mdx';
+import { gfm } from 'micromark-extension-gfm';
+import { mdxjs } from 'micromark-extension-mdxjs';
+import { findBodyFieldName } from '../utils/body-field.js';
+import { flattenGroupFields } from '../utils/flatten-group-fields.js';
+import { getErrorMessage } from '../utils/error.js';
+import { traverseFields } from './field-traversal.js';
+import { FORBIDDEN_ATTRIBUTES, SAFE_HTML_TAGS, isComponentName, allowlistIdentity, isMarkdownField, markdownPolicyOf, resolveMdxAllowlist, } from './mdx-allowlist.js';
+/** `entry:` is CanopyCMS's own link to an entry, which the site resolves to a path. */
+const SAFE_URL_SCHEMES = new Set(['http', 'https', 'mailto', 'tel', 'entry']);
+/** A `data:` URL is accepted only as a raster image, which no browser runs as a document. */
+const SAFE_DATA_URL = /^data:image\/(?:png|gif|jpe?g|webp|avif)[;,]/i;
+/**
+ * Attribute names, lower-cased with non-letters removed, that `SAFE_HTML_TAGS` load as a URL or
+ * that a component commonly passes on to one. `data` is left out: it is a URL only on `<object>`,
+ * which is not a safe tag, and a common component prop.
+ */
+const URL_ATTRIBUTES = new Set([
+    'action',
+    'cite',
+    'formaction',
+    'href',
+    'ping',
+    'poster',
+    'src',
+    'srcset',
+    'to',
+    'url',
+    'xlinkhref',
+]);
+/**
+ * Attributes, lower-cased, that `SAFE_HTML_TAGS` may carry, plus any `aria-*`. Anything else is
+ * refused on a tag, because a script the site loads can give an attribute meaning: Alpine's
+ * `x-init`, htmx's `hx-on:click`, or a `data-*` a page script `eval`s.
+ */
+const SAFE_HTML_ATTRIBUTES = new Set([
+    'abbr',
+    'align',
+    'alt',
+    'autoplay',
+    'cite',
+    'class',
+    'classname',
+    'colspan',
+    'controls',
+    'datetime',
+    'decoding',
+    'default',
+    'dir',
+    'download',
+    'headers',
+    'height',
+    'hidden',
+    'href',
+    'hreflang',
+    'id',
+    'kind',
+    'label',
+    'lang',
+    'loading',
+    'loop',
+    'media',
+    'muted',
+    'open',
+    'playsinline',
+    'poster',
+    'preload',
+    'rel',
+    'reversed',
+    'role',
+    'rowspan',
+    'scope',
+    'sizes',
+    'span',
+    'src',
+    'srclang',
+    'srcset',
+    'start',
+    'style',
+    'target',
+    'title',
+    'translate',
+    'type',
+    'valign',
+    'value',
+    'width',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** True when an ESTree expression is literal data: no identifier, call, function or spread. */
+function isStaticValue(node) {
+    if (!isRecord(node))
+        return false;
+    switch (node.type) {
+        case 'Literal':
+            return true;
+        case 'TemplateLiteral':
+            return Array.isArray(node.expressions) && node.expressions.length === 0;
+        case 'UnaryExpression':
+            return ((node.operator === '-' || node.operator === '+') &&
+                isRecord(node.argument) &&
+                node.argument.type === 'Literal' &&
+                typeof node.argument.value === 'number');
+        case 'ArrayExpression':
+            return (Array.isArray(node.elements) &&
+                node.elements.every((element) => element === null || isStaticValue(element)));
+        case 'ObjectExpression':
+            return (Array.isArray(node.properties) &&
+                // A method or accessor's value is a function, so the value check refuses it too.
+                node.properties.every((property) => isRecord(property) &&
+                    property.type === 'Property' &&
+                    property.computed === false &&
+                    isStaticValue(property.value)));
+        default:
+            return false;
+    }
+}
+/** The program MDX parsed an expression node's code into, if it did. */
+function estreeOf(node) {
+    return isRecord(node.data) ? node.data.estree : undefined;
+}
+/**
+ * True when an expression's parsed program holds no code: only comments, or one static value.
+ * A missing program (it was not parsed) holds code as far as this check knows.
+ */
+function isInertProgram(estree) {
+    if (!isRecord(estree) || !Array.isArray(estree.body))
+        return false;
+    if (estree.body.length === 0)
+        return true;
+    if (estree.body.length > 1)
+        return false;
+    const [statement] = estree.body;
+    return (isRecord(statement) &&
+        statement.type === 'ExpressionStatement' &&
+        isStaticValue(statement.expression));
+}
+/** The scheme a browser would read from `url`, lower-cased, or undefined for a relative URL. */
+function urlScheme(url) {
+    // Browsers drop ASCII tab and newline anywhere and C0 controls and spaces at the ends;
+    // dropping every one of them anywhere can only find a scheme where a browser finds none.
+    // eslint-disable-next-line no-control-regex
+    const compact = url.replace(/[\u0000-\u0020\u007f]/g, '');
+    return /^([a-z][a-z0-9+.-]*):/i.exec(compact)?.[1]?.toLowerCase();
+}
+function unsafeUrlScheme(url) {
+    const scheme = urlScheme(url);
+    if (scheme === undefined || SAFE_URL_SCHEMES.has(scheme))
+        return undefined;
+    if (scheme === 'data' && SAFE_DATA_URL.test(url.trim()))
+        return undefined;
+    return scheme;
+}
+/**
+ * The scheme of a value that runs script if it reaches an `href` or `src`, which a component may
+ * do with any prop: checked on every string a prop holds. `data:` is left to the URL attributes,
+ * since a data document runs in an opaque origin and prose often starts with "Data:".
+ */
+function scriptScheme(value) {
+    const scheme = urlScheme(value);
+    return scheme === 'javascript' || scheme === 'vbscript' ? scheme : undefined;
+}
+/** Every string in a static value: literals, template text, and array and object values. */
+function staticStrings(node) {
+    if (!isRecord(node))
+        return [];
+    switch (node.type) {
+        case 'Program':
+            return Array.isArray(node.body) ? node.body.flatMap(staticStrings) : [];
+        case 'ExpressionStatement':
+            return staticStrings(node.expression);
+        case 'Literal':
+            return typeof node.value === 'string' ? [node.value] : [];
+        case 'TemplateLiteral':
+            return Array.isArray(node.quasis)
+                ? node.quasis.flatMap((quasi) => isRecord(quasi) && isRecord(quasi.value) && typeof quasi.value.cooked === 'string'
+                    ? [quasi.value.cooked]
+                    : [])
+                : [];
+        case 'ArrayExpression':
+            return Array.isArray(node.elements) ? node.elements.flatMap(staticStrings) : [];
+        case 'ObjectExpression':
+            return Array.isArray(node.properties)
+                ? node.properties.flatMap((property) => isRecord(property) ? staticStrings(property.value) : [])
+                : [];
+        default:
+            return [];
+    }
+}
+/** Each URL a `srcset` names: the first token of every comma-separated candidate. */
+function srcsetUrls(value) {
+    return value
+        .split(',')
+        .map((candidate) => candidate.trim().split(/\s+/)[0] ?? '')
+        .filter((url) => url !== '');
+}
+/** Where an issue sits, as the editor shows it. */
+const at = (node) => (node.position ? ` (line ${node.position.start.line})` : '');
+function issue(node, message) {
+    return { message: `${message}${at(node)}`, line: node.position?.start.line };
+}
+function urlIssue(node, url, where) {
+    const scheme = unsafeUrlScheme(url);
+    if (scheme === undefined)
+        return undefined;
+    return issue(node, `The URL scheme "${scheme}:" is not allowed in ${where}; use http(s), mailto, tel, an entry link or a path on the site`);
+}
+/** The URLs and script schemes in one attribute value, which the base policy refuses. */
+function attributeValueIssues(node, tag, attributeName, value) {
+    const lower = attributeName.toLowerCase();
+    const isUrl = URL_ATTRIBUTES.has(lower.replace(/[^a-z]/g, ''));
+    if (isRecord(value) && (isUrl || !isInertProgram(estreeOf(value)))) {
+        return [
+            issue(node, isUrl
+                ? `${attributeName} on ${tag} must be a plain "string"`
+                : `${attributeName} on ${tag} must be a plain value, such as "text" or {300}`),
+        ];
+    }
+    if (isUrl && typeof value === 'string') {
+        const urls = lower === 'srcset' ? srcsetUrls(value) : [value];
+        return urls.flatMap((url) => urlIssue(node, url, `${attributeName} on ${tag}`) ?? []);
+    }
+    const strings = typeof value === 'string' ? [value] : isRecord(value) ? staticStrings(estreeOf(value)) : [];
+    return strings.flatMap((text) => {
+        const scheme = scriptScheme(text);
+        return scheme === undefined
+            ? []
+            : [issue(node, `The URL scheme "${scheme}:" is not allowed in ${attributeName} on ${tag}`)];
+    });
+}
+/**
+ * The value an allowlist's value list matches: a string, `true` for a bare attribute, or a
+ * single literal expression. Undefined for anything else, which no list matches.
+ */
+function plainValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value;
+    const estree = isRecord(value) ? estreeOf(value) : undefined;
+    if (!isRecord(estree) || !Array.isArray(estree.body) || estree.body.length !== 1)
+        return undefined;
+    const [statement] = estree.body;
+    if (!isRecord(statement) || statement.type !== 'ExpressionStatement')
+        return undefined;
+    const expression = statement.expression;
+    if (!isRecord(expression) || expression.type !== 'Literal')
+        return undefined;
+    const literal = expression.value;
+    return typeof literal === 'string' || typeof literal === 'number' || typeof literal === 'boolean'
+        ? literal
+        : undefined;
+}
+/** How a refusal shows an attribute as written. */
+function showAttribute(attributeName, value) {
+    if (value === null || value === undefined)
+        return attributeName;
+    if (typeof value === 'string')
+        return `${attributeName}="${value}"`;
+    return `${attributeName}={…}`;
+}
+const listOf = (names) => [...names].sort().join(', ');
+/** A string allowance's `maxLength` (`null`: uncapped), or `undefined` for any other allowance. */
+function stringAllowance(allowed) {
+    if (allowed === 'string')
+        return { maxLength: null };
+    if (isRecord(allowed) && allowed.type === 'string') {
+        return { maxLength: allowed.maxLength ?? null };
+    }
+    return undefined;
+}
+function checkJsxElement(node, allow) {
+    const name = node.name;
+    // A fragment (`<>…</>`) renders its children and nothing else.
+    if (name === null || name === undefined) {
+        return allow.fragments ? [] : [issue(node, 'Fragments (<>…</>) are not allowed here')];
+    }
+    const tag = `<${name}>`;
+    const isComponent = isComponentName(name);
+    if (!isComponent && !SAFE_HTML_TAGS.has(name)) {
+        return [
+            issue(node, name.includes('.')
+                ? `${tag} is not allowed: use a component by its plain name`
+                : `${tag} is not allowed: it is not one of the HTML tags a body may use, so use one of the site's components instead`),
+        ];
+    }
+    if (!isComponent && !allow.htmlTags.has(name)) {
+        const allowed = allow.htmlTags.size === 0 ? 'none' : listOf(allow.htmlTags);
+        return [issue(node, `${tag} is not allowed here; allowed HTML tags: ${allowed}`)];
+    }
+    if (isComponent && allow.components !== undefined && !allow.components.has(name)) {
+        return [
+            issue(node, allow.components.size === 0
+                ? `Component ${tag} is not allowed: no components are allowed here`
+                : `Component ${tag} is not allowed here; allowed: ${listOf(allow.components.keys())}`),
+        ];
+    }
+    const props = isComponent ? allow.components?.get(name) : undefined;
+    const issues = [];
+    const attributes = Array.isArray(node.attributes) ? node.attributes : [];
+    for (const attribute of attributes) {
+        if (!isRecord(attribute) ||
+            attribute.type !== 'mdxJsxAttribute' ||
+            typeof attribute.name !== 'string') {
+            issues.push(issue(node, `{…} spread attributes are not allowed on ${tag}`));
+            continue;
+        }
+        const attributeName = attribute.name;
+        const value = attribute.value;
+        const lower = attributeName.toLowerCase();
+        if (props !== undefined && !props.has(attributeName)) {
+            issues.push(issue(node, props.size === 0
+                ? `Prop ${attributeName} on ${tag} is not allowed: ${tag} takes no props here`
+                : `Prop ${attributeName} on ${tag} is not allowed here; allowed: ${listOf(props.keys())}`));
+            continue;
+        }
+        // A tag's `on…` attribute is a handler in any spelling; a component's prop is one by React's
+        // convention, so `online` or `onlyMobile` stays a plain prop.
+        if (isComponent ? /^on[A-Z]/.test(attributeName) : /^on/.test(lower)) {
+            issues.push(issue(node, `${attributeName} on ${tag} is not allowed: event handlers run code`));
+            continue;
+        }
+        if (FORBIDDEN_ATTRIBUTES.has(lower) ||
+            (!isComponent && !SAFE_HTML_ATTRIBUTES.has(lower) && !lower.startsWith('aria-'))) {
+            issues.push(issue(node, `${attributeName} on ${tag} is not allowed`));
+            continue;
+        }
+        if (isRecord(value) && !allow.expressions) {
+            issues.push(issue(node, `${attributeName} on ${tag} must be a plain "string": {…} values are not allowed here`));
+            continue;
+        }
+        const found = attributeValueIssues(node, tag, attributeName, value);
+        if (found.length > 0) {
+            issues.push(...found);
+            continue;
+        }
+        const values = props?.get(attributeName);
+        const stringOnly = stringAllowance(values);
+        if (stringOnly !== undefined) {
+            if (typeof value !== 'string') {
+                issues.push(issue(node, `Prop ${attributeName} on ${tag} must be a quoted string, e.g. ${attributeName}="…"`));
+            }
+            else {
+                const length = [...value].length;
+                if (stringOnly.maxLength !== null && length > stringOnly.maxLength) {
+                    issues.push(issue(node, `Prop ${attributeName} on ${tag} must be at most ${stringOnly.maxLength} characters; it has ${length}`));
+                }
+            }
+        }
+        else if (Array.isArray(values)) {
+            const plain = plainValue(value);
+            if (plain === undefined || !values.includes(plain)) {
+                const allowed = values.map((v) => JSON.stringify(v)).join(', ');
+                issues.push(issue(node, `${showAttribute(attributeName, value)} on ${tag} is not allowed here; allowed values: ${allowed}`));
+            }
+        }
+    }
+    return issues;
+}
+function checkNode(node, definitions, allow) {
+    const issues = [];
+    switch (node.type) {
+        case 'mdxjsEsm':
+            issues.push(issue(node, 'import/export statements are not allowed: they run as code'));
+            break;
+        case 'mdxFlowExpression':
+        case 'mdxTextExpression':
+            if (!allow.expressions) {
+                issues.push(issue(node, '{…} expressions are not allowed here, not even comments or plain values'));
+            }
+            else if (!isInertProgram(estreeOf(node))) {
+                issues.push(issue(node, '{…} expressions are not allowed: they run as code. A comment {/* … */} or a plain value such as {" "} is fine'));
+            }
+            break;
+        case 'mdxJsxFlowElement':
+        case 'mdxJsxTextElement':
+            issues.push(...checkJsxElement(node, allow));
+            break;
+        case 'link':
+        case 'image':
+        case 'definition': {
+            const found = node.url === undefined ? undefined : urlIssue(node, node.url, URL_SITES[node.type] ?? '');
+            if (found)
+                issues.push(found);
+            break;
+        }
+        // A reference loads its definition's URL.
+        case 'linkReference':
+        case 'imageReference': {
+            const url = node.identifier === undefined ? undefined : definitions.get(node.identifier);
+            const found = url === undefined ? undefined : urlIssue(node, url, URL_SITES[node.type] ?? '');
+            if (found)
+                issues.push(found);
+            break;
+        }
+    }
+    for (const child of node.children ?? [])
+        issues.push(...checkNode(child, definitions, allow));
+    return issues;
+}
+/** How an issue names each node that carries a URL. */
+const URL_SITES = {
+    link: 'a link',
+    image: 'an image',
+    definition: 'a definition',
+    linkReference: 'a link reference',
+    imageReference: 'an image reference',
+};
+/** Each definition's URL by label. The first definition of a label is the one that applies. */
+function collectDefinitions(node, into = new Map()) {
+    if (node.type === 'definition' && node.identifier !== undefined && node.url !== undefined) {
+        if (!into.has(node.identifier))
+            into.set(node.identifier, node.url);
+    }
+    for (const child of node.children ?? [])
+        collectDefinitions(child, into);
+    return into;
+}
+function parse(source, dialect, withGfm) {
+    const extensions = [...(withGfm ? [gfm()] : []), ...(dialect === 'mdx' ? [mdxjs()] : [])];
+    const mdastExtensions = [
+        ...(withGfm ? [gfmFromMarkdown()] : []),
+        ...(dialect === 'mdx' ? [mdxFromMarkdown()] : []),
+    ];
+    return fromMarkdown(source, { extensions, mdastExtensions });
+}
+/**
+ * Every construct in `source` that runs code, or loads a URL that does, when it renders.
+ * @internal Exported for tests.
+ */
+export function findUnsafeMarkdown(source, dialect, allow = resolveMdxAllowlist(undefined, undefined)) {
+    // Line endings are not part of what MDX compiles, and a save may turn CRLF into LF.
+    const field = source.replace(/\r\n?/g, '\n');
+    const parses = [];
+    for (const withGfm of [false, true]) {
+        let tree;
+        try {
+            tree = parse(field, dialect, withGfm);
+        }
+        catch (err) {
+            return [
+                { message: `This MDX does not parse, so it cannot be checked: ${getErrorMessage(err)}` },
+            ];
+        }
+        let found;
+        try {
+            found = checkNode(tree, collectDefinitions(tree), allow);
+        }
+        catch (err) {
+            // Nesting deep enough to exhaust the stack.
+            return [{ message: `This body is too deeply nested to check: ${getErrorMessage(err)}` }];
+        }
+        parses.push(found);
+    }
+    // Both parses report most constructs; each is reported as often as the parse that saw it most.
+    const id = (item) => item.message;
+    const [plain = [], withGfm = []] = parses;
+    const unmatched = new Map();
+    for (const item of plain)
+        unmatched.set(id(item), (unmatched.get(id(item)) ?? 0) + 1);
+    const issues = [...plain];
+    for (const item of withGfm) {
+        const count = unmatched.get(id(item)) ?? 0;
+        if (count > 0)
+            unmatched.set(id(item), count - 1);
+        else
+            issues.push(item);
+    }
+    // The same text runs differently as markdown and as MDX, and a field may hold only what its own
+    // allowlist accepts, so both are part of the key.
+    const key = `${dialect}\0${allowlistIdentity(allow)}\0${field}`;
+    return issues.map((item) => ({ ...item, key }));
+}
+/** The field's one message: its first issue, and how many more there are. */
+function toFieldError(fieldPath, issues) {
+    const [first, ...rest] = issues;
+    const more = rest.length === 0 ? '' : ` (and ${rest.length} more)`;
+    return { fieldPath, message: `${first?.message ?? ''}${more}` };
+}
+function findInValue(fieldPath, value, { dialect, allow }) {
+    const values = Array.isArray(value) ? value : [value];
+    const findings = [];
+    values.forEach((item, index) => {
+        if (typeof item !== 'string' || item === '')
+            return;
+        const issues = findUnsafeMarkdown(item, dialect, allow);
+        if (issues.length === 0)
+            return;
+        findings.push({
+            fieldPath: Array.isArray(value) ? `${fieldPath}[${index}]` : fieldPath,
+            issues,
+        });
+    });
+    return findings;
+}
+/**
+ * The policy's issues in one entry's on-disk-shaped data, the body merged in under the schema's
+ * body field name. The body is checked as `markdownPolicyOf` says for its field and the entry's
+ * format, even when the schema declares no body field; it is exempt only when its field is
+ * `executable`. `siteAllow` is the config's `mdxAllow`, under each field's own.
+ */
+export function findMarkdownSafetyIssues(fields, format, data, siteAllow) {
+    const hasBody = format === 'md' || format === 'mdx';
+    const bodyName = hasBody ? findBodyFieldName(fields) : undefined;
+    const findings = [];
+    if (hasBody && bodyName !== undefined) {
+        const found = flattenGroupFields(fields).find((field) => field.name === bodyName);
+        const bodyField = found !== undefined && isMarkdownField(found) ? found : undefined;
+        const policy = markdownPolicyOf(bodyField, siteAllow, format);
+        if (policy !== undefined)
+            findings.push(...findInValue(bodyName, data[bodyName], policy));
+    }
+    findings.push(...traverseFields(fields, data, ({ field, value, path }) => {
+        if (path === bodyName || !isMarkdownField(field))
+            return [];
+        const policy = markdownPolicyOf(field, siteAllow);
+        return policy === undefined ? [] : findInValue(path, value, policy);
+    }));
+    return findings;
+}
+/** A field with list and block positions dropped, so reordering items keeps a match. */
+const site = (fieldPath) => fieldPath.replace(/\[\d+\]/g, '');
+/**
+ * The field occurrence a finding stands for: its site and key, which every one of its issues
+ * carries, or undefined for a finding whose one issue has none, such as a body that does not parse.
+ */
+function occurrenceOf(finding) {
+    const key = finding.issues[0]?.key;
+    return key === undefined ? undefined : `${site(finding.fieldPath)}\0${key}`;
+}
+/**
+ * Splits a save's findings into those it adds, which refuse it, and those of a field saved exactly
+ * as the stored entry held it, which it keeps. Fields are matched by site and key, one stored field
+ * for one saved field, so a second copy of a stored field is refused, as is one moved to a field of
+ * another name or allowlist. A finding with an unkeyed issue is never kept.
+ */
+export function splitByStored(found, stored) {
+    const available = new Map();
+    const storedSites = new Set(stored.map((finding) => site(finding.fieldPath)));
+    for (const finding of stored) {
+        const id = occurrenceOf(finding);
+        if (id !== undefined)
+            available.set(id, (available.get(id) ?? 0) + 1);
+    }
+    const refused = [];
+    const kept = [];
+    for (const finding of found) {
+        const id = occurrenceOf(finding);
+        const count = id === undefined ? 0 : (available.get(id) ?? 0);
+        if (id !== undefined && count > 0) {
+            available.set(id, count - 1);
+            kept.push(toFieldError(finding.fieldPath, finding.issues));
+            continue;
+        }
+        const error = toFieldError(finding.fieldPath, finding.issues);
+        refused.push(storedSites.has(site(finding.fieldPath))
+            ? {
+                ...error,
+                message: `This field already holds content it refuses, so it saves only unchanged or with that content removed. ${error.message}`,
+            }
+            : error);
+    }
+    return { refused, kept };
+}

package/dist/validation/mdx-allowlist.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What an MDX body may hold, as `markdown-safety.ts` enforces it and as config validation and
+ * the editor read it. Dependency-free, so config schemas and the client bundle can import it
+ * without the MDX parser.
+ *
+ * An `MdxAllowlist` only narrows the base policy: a tag outside `SAFE_HTML_TAGS`, a name that is
+ * not a component, and a prop the base policy refuses are config errors, and every base rule
+ * still runs on what the allowlist accepts.
+ */
+import type { ContentFormat, FieldConfig, MarkdownFieldConfig, MdxAllowlist, MdxPropAllow } from '../config/types.js';
+/** HTML tags an MDX body may use: content elements whose attributes carry no code. */
+export declare const SAFE_HTML_TAGS: ReadonlySet<string>;
+export declare function isComponentName(name: string): boolean;
+/** Attribute names, lower-cased, that put markup or a document into the page. */
+export declare const FORBIDDEN_ATTRIBUTES: ReadonlySet<string>;
+/**
+ * A component prop the base policy always refuses: an event handler by React's convention
+ * (`onClick`, while `online` stays a plain prop), or one in `FORBIDDEN_ATTRIBUTES`.
+ */
+export declare function isRefusedComponentProp(name: string): boolean;
+/**
+ * An allowlist with the defaults filled in. `components` undefined: any component; a component's
+ * props undefined: any prop.
+ */
+export interface ResolvedMdxAllowlist {
+    components: ReadonlyMap<string, ReadonlyMap<string, MdxPropAllow> | undefined> | undefined;
+    htmlTags: ReadonlySet<string>;
+    expressions: boolean;
+    fragments: boolean;
+}
+/**
+ * A string two allowlists share only if they accept the same MDX. Two spellings of one allowlist
+ * (value order, the full tag set listed out) can differ, which only ever refuses keeping content.
+ */
+export declare function allowlistIdentity(allow: ResolvedMdxAllowlist): string;
+/** Each key the field sets replaces the site's; a key neither sets keeps the base policy. */
+export declare function resolveMdxAllowlist(field: MdxAllowlist | undefined, site: MdxAllowlist | undefined): ResolvedMdxAllowlist;
+export declare function isMarkdownField(field: FieldConfig): field is MarkdownFieldConfig;
+/** How a field's content is checked: as markdown or MDX, and what MDX it accepts. */
+export interface MarkdownPolicy {
+    dialect: 'md' | 'mdx';
+    allow: ResolvedMdxAllowlist;
+}
+/**
+ * The policy the server enforces and the editor follows, or undefined for an `executable` field. A
+ * field is MDX when typed `mdx` or set `renderAs: 'mdx'`. An entry's body (`bodyFormat` given, its
+ * field possibly undeclared) follows the entry instead: MDX in an `mdx` entry, and in an `md` entry
+ * only with `renderAs: 'mdx'`, since a site renders an `md` file as markdown.
+ */
+export declare function markdownPolicyOf(field: MarkdownFieldConfig | undefined, site: MdxAllowlist | undefined, bodyFormat?: ContentFormat): MarkdownPolicy | undefined;
+/**
+ * Why a markdown or mdx field's `renderAs`, `mdxAllow` and `executable` contradict each other, or
+ * undefined. An allowlist that cannot apply would look like protection it is not.
+ */
+export declare function markdownFieldOptionsError(field: MarkdownFieldConfig): string | undefined;