@hyperframes/core 0.7.105 → 0.7.107

package/dist/utils/richTextSanitize.js

@@ -0,0 +1,227 @@
+/**
+ * What inline formatting a composition file is allowed to receive.
+ *
+ * Editing text in the Studio preview can style a run of characters, which means
+ * markup now travels from a contenteditable element into a file on disk. This
+ * module is the only thing deciding what may make that trip. The server write
+ * boundary applies it unconditionally before returning composition bytes.
+ *
+ * One module rather than two implementations. Two would drift, and the drift
+ * would be a security bug rather than an inconsistency.
+ *
+ * It works on an element's subtree in place. Untrusted markup must be parsed in
+ * an inert document before this function receives it.
+ */
+/** Tags an inline text edit may contain. Everything else is not text styling. */
+const FORMATTING_TAGS = new Set(["SPAN", "B", "STRONG", "I", "EM", "U", "BR"]);
+/**
+ * Style properties a formatting tag may carry.
+ *
+ * This was paint-only, on the reasoning that a property which moves or resizes
+ * text would let an edit inside one element change the composition's layout,
+ * and layout is the design panel's job. The reasoning was wrong about who was
+ * being restricted: the design panel writes exactly these typography
+ * properties onto exactly these spans, as its text layers. Sanitizing them
+ * away did not stop text from changing layout, it deleted the layout the user
+ * had already set — colouring one word silently dropped a sibling layer's font
+ * size. The line that matters is the one below, values that reach outside the
+ * stylesheet, not which of its own properties the editor is allowed to keep.
+ */
+const FORMATTING_STYLE_PROPS = new Set([
+    "color",
+    "background-color",
+    "font-weight",
+    "font-style",
+    "text-decoration-line",
+    "font-family",
+    "font-size",
+    "letter-spacing",
+    "line-height",
+    // Paints the glyph fill and inherits, so an ancestor that sets it wins over
+    // any `color` below. The editor mirrors a run's colour into it when that is
+    // happening, and stripping it here would put the colour back to invisible.
+    "-webkit-text-fill-color",
+]);
+// Keep this list limited to properties whose grammar cannot fetch a resource.
+// Adding a URL-consuming property also requires decoding CSS escapes before
+// UNSAFE_VALUE can be a sufficient guard.
+/**
+ * Attributes a formatting tag may carry.
+ *
+ * The identity a text layer is tracked by. Everything else is dropped: a
+ * contenteditable is a paste target, and an event handler or an id that
+ * shadows a composition's own is not formatting.
+ */
+const FORMATTING_ATTRS = new Set(["data-hf-text-key", "data-hf-id"]);
+/**
+ * What those attributes are allowed to look like: a bare token, nothing else.
+ * `:` is deliberate because text keys use selector-like tokens such as
+ * `child:1`; neither allowed attribute is interpreted as a URL.
+ */
+const SAFE_ATTR_VALUE = /^[A-Za-z0-9_:-]+$/;
+/**
+ * Tags dropped whole rather than unwrapped.
+ *
+ * Everything else is unwrapped, so an unexpected tag costs the user its
+ * formatting and not their words. These are the ones whose contents are not
+ * words: unwrapping a script would turn its source into visible text.
+ */
+const OPAQUE_TAGS = new Set([
+    "SCRIPT",
+    "STYLE",
+    "TEMPLATE",
+    "NOSCRIPT",
+    "IFRAME",
+    "OBJECT",
+    "EMBED",
+    "SVG",
+    "MATH",
+]);
+/** Anything that reaches out of the stylesheet, in a property that should not. */
+const UNSAFE_VALUE = /url\(|expression\(|javascript:|vbscript:|@import|<\//i;
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+export function isRichTextFormattingTag(tagName) {
+    return FORMATTING_TAGS.has(tagName.toUpperCase());
+}
+/** Whether an attribute survives the rich-text persistence boundary. */
+export function isRichTextFormattingAttribute(name, value) {
+    return FORMATTING_ATTRS.has(name.toLowerCase()) && SAFE_ATTR_VALUE.test(value);
+}
+/** Whether a declaration survives the rich-text persistence boundary. */
+export function isRichTextFormattingStyle(property, value) {
+    return (FORMATTING_STYLE_PROPS.has(property.toLowerCase()) &&
+        value.length > 0 &&
+        !UNSAFE_VALUE.test(value));
+}
+function isElementNode(node) {
+    return node.nodeType === ELEMENT_NODE;
+}
+/**
+ * Strip everything but allowed formatting from an element's contents, in place.
+ *
+ * The element itself is never touched, only what is inside it. Callers own the
+ * element, and it is the composition's, not the editor's, to rewrite.
+ *
+ * When the children came from untrusted markup, callers must parse that markup
+ * into an inert document (for example linkedom or a detached DOMParser document)
+ * first. Never assign untrusted HTML to a live DOM element and then call this
+ * function: active content can run before sanitization begins.
+ */
+export function sanitizeRichTextChildren(parent) {
+    const pending = Array.from(parent.childNodes, (node) => ({ phase: "visit", node })).reverse();
+    // Post-order without recursion: adversarially deep pasted markup must not
+    // exhaust either the server or browser call stack.
+    for (let frame = pending.pop(); frame; frame = pending.pop()) {
+        if (frame.phase === "sanitize") {
+            if (!FORMATTING_TAGS.has(frame.tag))
+                unwrap(frame.element);
+            else
+                stripAttributes(frame.element);
+            continue;
+        }
+        const child = frame.node;
+        if (child.nodeType === TEXT_NODE)
+            continue;
+        if (!isElementNode(child)) {
+            // Comments and processing instructions are neither words nor formatting.
+            child.parentNode?.removeChild(child);
+            continue;
+        }
+        const element = child;
+        const tag = element.tagName.toUpperCase();
+        if (OPAQUE_TAGS.has(tag)) {
+            element.parentNode?.removeChild(element);
+            continue;
+        }
+        pending.push({ phase: "sanitize", element, tag });
+        for (const descendant of Array.from(element.childNodes).reverse()) {
+            pending.push({ phase: "visit", node: descendant });
+        }
+    }
+}
+/** Replace an element with its own children, keeping their order and place. */
+function unwrap(element) {
+    const parent = element.parentNode;
+    if (!parent)
+        return;
+    while (element.firstChild)
+        parent.insertBefore(element.firstChild, element);
+    parent.removeChild(element);
+}
+/** Leave a kept tag with a filtered style attribute and its identity, no more. */
+function stripAttributes(element) {
+    const style = element.getAttribute("style");
+    for (const name of Array.from(element.getAttributeNames())) {
+        const value = element.getAttribute(name) ?? "";
+        if (isRichTextFormattingAttribute(name, value))
+            continue;
+        element.removeAttribute(name);
+    }
+    if (style === null)
+        return;
+    const safe = filterStyle(style);
+    if (safe)
+        element.setAttribute("style", safe);
+    else
+        element.removeAttribute("style");
+}
+/** Keep only the allowlisted declarations, and only if their values are inert. */
+function filterStyle(style) {
+    return splitDeclarations(style)
+        .map((declaration) => {
+        const colon = declaration.indexOf(":");
+        if (colon === -1)
+            return null;
+        const property = declaration.slice(0, colon).trim().toLowerCase();
+        const value = declaration.slice(colon + 1).trim();
+        if (!isRichTextFormattingStyle(property, value))
+            return null;
+        return `${property}: ${value}`;
+    })
+        .filter((declaration) => declaration !== null)
+        .join("; ");
+}
+function isQuoteDelimiter(char) {
+    return char === "'" || char === '"';
+}
+function nextParenthesisDepth(depth, char) {
+    if (char === "(")
+        return depth + 1;
+    if (char === ")")
+        return Math.max(0, depth - 1);
+    return depth;
+}
+function isDeclarationSeparator(char, depth, quote) {
+    return char === ";" && depth === 0 && quote === null;
+}
+/**
+ * Split on the semicolons that separate declarations, not the ones inside a
+ * value. `color: rgb(1, 2, 3)` is one declaration however many separators its
+ * value contains.
+ */
+function splitDeclarations(style) {
+    const declarations = [];
+    let current = "";
+    let depth = 0;
+    let quote = null;
+    for (const char of style) {
+        if (char === quote)
+            quote = null;
+        else if (quote === null && isQuoteDelimiter(char))
+            quote = char;
+        else if (isDeclarationSeparator(char, depth, quote)) {
+            declarations.push(current);
+            current = "";
+            continue;
+        }
+        else if (quote === null) {
+            depth = nextParenthesisDepth(depth, char);
+        }
+        current += char;
+    }
+    if (current.trim())
+        declarations.push(current);
+    return declarations;
+}
+//# sourceMappingURL=richTextSanitize.js.map

package/dist/utils/richTextSanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"richTextSanitize.js","sourceRoot":"","sources":["../../src/utils/richTextSanitize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.7.105",
+  "version": "0.7.107",
   "description": "",
   "repository": {
     "type": "git",
@@ -42,6 +42,10 @@
       "import": "./dist/utils/htmlAttrSafety.js",
       "types": "./dist/utils/htmlAttrSafety.d.ts"
     },
+    "./rich-text-sanitize": {
+      "import": "./dist/utils/richTextSanitize.js",
+      "types": "./dist/utils/richTextSanitize.d.ts"
+    },
     "./composition-contract": {
       "import": "./dist/compositionContract.js",
       "types": "./dist/compositionContract.d.ts"
@@ -218,9 +222,9 @@
     "bpm-detective": "^2.0.5",
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
-    "@hyperframes/lint": "0.7.105",
-    "@hyperframes/studio-server": "0.7.105",
-    "@hyperframes/parsers": "0.7.105"
+    "@hyperframes/lint": "0.7.107",
+    "@hyperframes/studio-server": "0.7.107",
+    "@hyperframes/parsers": "0.7.107"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",